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Preface 



For your convenience and ease of reference, this manual is divided into 
two volumes. Volume 1 : How SOS Works describes the operating system 
of the Apple III. Volume 2: The SOS Calls defines the individual SOS calls. 
Notice that the sequence of chapter numbers in Volume 1 continues 
unchanged into Volume 2. 



Scope of this Manual 



This manual describes SOS (pronounced "sauce"), the Sophisticated 
Operating System of the Apple III. With the information in this manual 
you'll be able to write assembly-language programs that use the full 
powerof the Apple III. 

However, this manual is not a course in assembly-language programming. 
It assumes that you can program in assembly language and know the 
architecture of the 6502 microprocessor upon which the Apple III is 
based; it will explain howthearchitectureof the Apple III processor goes 
beyond that of the standard 6502. If you need more information on 6502 
assembly-language programming, refer to one of the books listed in the 
bibliography of this manual. 

The companion volume to this manual, Xhe Apple III SOS Device Driver 
Writer's Guide, contains the information you may need about the interface 
hardware of the Apple 1 1 1 , and tells how to create device drivers to use that 
hardware. If you wish to create custom interface software or hardware for 
the Apple III, read the present manual before turning to the Apple III SOS 
Device Driver Writer's Guide. 
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Using this Manual 



Before you begin with tiiis manual, you should prepare yourself by 
reading the following: 

• the Apple III Owner's Guide introduces you to some of the 
fundamental features of the Apple III— features that you will 
be exploring more deeply in this manual; 

• the Apple III Standard Device Drivers Manual describes the 
workings of the Apple Ill's video screen, keyboard, graphics, 
and communications interfaces; 

• the Apple III Pascal Program Preparation Tools manual explains 
the use of the Apple 1 1 1 Pascal Assembler, which is the only 
assembler that works with SOS. 

You should also finish reading this preface, to learn about the notation and 
examples used in this manual. 

About tiie Examples 



Included in this manual are many sample programs and code fragments. 
These are intended as demonstrations only. In order to illustrate their 
concepts as well as possible, they are written to be clear and concise, 
without necessarily being efficient or comprehensive. 

Notation and Symbols 



Some special symbols and numeric notations are used throughout this 
manual. 

Numeric Notation 

We assume that you are familiar with the hexadecimal (hex) numbering 
system. All hexadecimal numbers in the text and tables of this manual are 
preceded by a dollar sign ($). Any number in the text, a table, or 
illustration that is not preceded by a dollar sign is a decimal number 
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Preface xix 



Program listings from the Apple III Pascal Assembler, however, do not 
prefix hex numbers with dollar signs. In such listings, you can distinguish 
decimal numbers from hex by the fact that decimal numbers end with a 
decimal point (. ). You can distinguish hex numbers from labels by the fact 
that hex numbers always begin with a digit from to 9, and labels always 
begin with a letter. 

Type Notation in Text Notation in Listings 



Decimal 255 255. 

Hexadecimal $3A5 3A5 

Hexadecimal $BAD1 0BAD1 

Label BAD1 BAD1 

Tabie 0-1 . Numeric Notation 

Additional notations are introduced in Chapter 1 . 



Speciai Symbois 

Four special symbols are used in this manual to emphasize information 
about helpful or unusual features of the system. 




This symbol precedes a paragraph that contains especially useful 
information. 



Watch out! This symbol precedes a paragraph that warns you to 
be careful. 




Stop! This symbol precedes a paragraph warning you that you 
are about to destroy data or harm hardware. 



This symbol precedes a paragraph that Is specific to versions 1.1, 
1 .2, and 1 .3 of SOS. Note especially that, although the symbol 
indicates version 1 .2, it is also applicable to versions 1 .1 and 1 .3. 
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1. 1 About Operating Systems 



An operating system is the traffic controller of a computer system. A 
well-designed operating system increases the power and usefulness of a 
computer in three important ways. First, an operating system establishes 
an abstract machine that is defined by its concepts and models, rather 
than by the physical attributes of particular hardware. Second, it acts as 
a resource manager, to ease the programming task. Finally, it provides 
a common foundation for software. 

If you are an experienced programmer of small computers, 
such as the Apple 1 1 , but you have never written large programs 
for a machine with an operating system, you should pay 
particular attention to this section. 

1.1.1 An Abstract Machine 

The low-level programming language of a computer is determined 
not only by its central processor, but by its operating system as well. 
The operating system is thus an essential part of the programming 
environment: knowing how it works lets you write programs that use 
the full power of the machine. 

Most importantly, the combination of hardware and operating system 
software creates an abstract machine that is neither the hardware nor 
the operating system, but a synthesis of both. This is the machine you 
program. 

The major advantage of the abstract-machine concept is that a program 
written for the abstract machine is not bound by the current configuration 
of the hardware. The operating system can compensate for expansions, 
enhancements, or changes in hardware, making these changes invisible 
to the programs. Thus programs properly written for an abstract machine 
need not be modified to respond to changes or improvements in the 
hardware. 



1.1.2 A Resource Manager 

An operating system also controls the flow of information into, out of, 
and within the computer It provides standard ways to store and retrieve 
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information on storage devices, communicate with and control 
input/output devices, and allocate memory to programs and data. It also 
provides certain "housekeeping" functions, such as reading and setting 
the system clock. 

The operating system saves you work. You don't have to write your own 
procedures for disk-access, communications, or memory-management: 
the operating system performs such functions for you. 

1. 1.3 A Common Foundation for Software 

An operating system also provides a common base on which to build 
integrated applications. This, above all, promotes compatibility between 
programs and data. If two programs use the same file structure and the 
same memory-management techniques, it's much easier to make the 
programs work with each other and share data. If all mass storage devices 
support a common file structure, it is much easier for a program to expand 
its capacity by substituting a larger device. 

Any service provided by SOS is provided only by SOS. The 
continued correct operation of your program under future 
versions can be assured only if you use the services provided 
and make no attempt to circumvent SOS. 

1.2 Overview of ttie Appie ill 



The Apple Ill/SOS Abstract Machine has six principal parts 
(see Figure 1-1): 

• An interpreter, which is the program executed at boot time; 

• The operating system, SOS; 

• Memory; 

• A set of files, for the storage and transfer of information; 

• A set of devices and drivers, for the communication of 
information; and 

• The 6502 instruction set, with extended addressing capabilities. 
All of these rest on a base created by the hardware of the machine. 
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Figure 1-1. The Apple Ill/SOS Abstract Machine 
The rest of this section describes these parts in brief. 
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1.2.1 The Interpreter 

An interpreter is an assembly-language program that starts automatically 
when SOS boots. Interpreters include the Business BASIC and Pascal 
language interpreters, as well as the application program Apple Writer III. 

Only one interpreter can reside in the system at a time. An interpreter 
is loaded each time the system is booted; the system cannot operate 
without an interpreter. In addition, language interpreters such as Pascal 
and BASIC allow separate assembly-language routines, called modules, 
to be loaded and executed. 

An interpreter consists of 6502 assembly-language code, including SOS 
calls. The construction and execution of interpreters and modules is 
described in Chapter 7. 

1.2.2 SOS 

SOS is the operating system of the Apple lll.lt provides a standard 
interface between the interpreter and the computer's hardware. 
An interpreter communicates with SOS by making subroutine-like 
calls to SOS. SOS returns the results of each call to the interpreter. 
SOS calls are of four types: 

• File management calls read, write, create, and delete files. 

• Device management calls read the status of a device or 
control the device. 

• Utility management calls provide access to the system clock, 
joystick, and event fence. 

• Memory management calls allocate and deallocate memory for 
the interpreter. 

SOS also controls all asynchronous operations of the computer, through 
the mechanisms of interrupts and events, as described in Chapter 6. An 
interrupt from a device is detected by SOS and handled, under the control 
of SOS, by an interrupt handler in that device's driver. An event is detected 
by a device driver and handled, under the control of SOS, by an event- 
handler subroutine in the interpreter. 
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SOS is always resident in the system and is loaded from the boot disk's 
SOS.KERNEL and SOS.DRIVER files when the system is booted. The 
SOS.KERNEL file contains that part of the operating system that must 
always be present for the Apple I II to function and which does not change 
from machine to machine: file management, memory management, utility 
management. Some device management functions, such as translating 
file calls into calls to device drivers, are also in the SOS kernel. The Disk 1 1 1 
driver is included in the SOS kernel because the Apple III system always 
has a built-in Disk III. 

The SOS.DRIVER file includes other device management functions. 
This file, which is also loaded at boot time, contains the drivers you can 
reconfigure or remove. The device drivers provide a way for a specific 
device to support the general concept of a file. For example, you can write 
a program to send output to the driver .PRINTER . The program contains 
no information about individual printers: it merely tells SOS to print so 
many bytes on the printer represented by .PRINTER . The driver 
.PRINTER translates the SOS calls into the control codes for the specific 
printer it is written for To use a different printer, you need only configure 
a different .PRINTER driver into the operating system. 

You can find more information about the standard device drivers 
that control the text and graphics displays, the keyboard, and the 
communications ports in the Apple III Standard Device Drivers Manual; 
information about other drivers is in the manuals for their devices; 
information about creating your own device drivers is in the >App/e /// 
SOS Device Driver Writer's Guide. 



1.2.3 Memory 

Although the standard addressing space of the 6502 microprocessor is 
64K bytes, the Apple III machine architecture and SOS provide efficient 
access to a maximum of 51 2K bytes of memory through the use of two 
enhanced addressing modes. These modes are described in Chapter 2. 

Current hardware supports up to 256K bytes. 




Several SOS calls create a memory management and allocation system. 
An interpreter can cause SOS to find an unused segment of memory, and 
return that segment's size and location. SOS keeps track of all allocated 
segments, so that a program that uses only SOS-allocated segments 
cannot accidentally destroy programs or data used by other parts of 
the system. 

The memory management system also allows an interpreter to acquire 
additional memory. This means that an interpreter need not be restricted 
to the use of a specific area of memory, so that the interpreter will run 
without modification on machines of different memory sizes: the only 
difference will be in performance. 

SOS acts as a memory bookkeeper, keeping track of memory allocated 
to the interpreter, its modules, and the operating system. This bookkeeper 
notes whether memory allocation ever violates the rules (that is, whether 
the same memory space is ever allocated to two programs at the same 
time); but it does not halt a program that breaks the rules, so the 
programmer must exercise care. An executing program has access to 
all memory within its own module. Any time it requests additional space, 
it should release it as soon as it is not needed. 



1.2.4 Files 

Files are the principal means of data storage in the Apple 1 1 1. A file is simply 
a standardized means by which information is organized and accessed 
on a peripheral device. All programs and data (even the operating system 
itself) are stored in files. All devices are represented as files. 

The way a file is used is independent of the way the hardware actually 
accesses that file. Files can be either on random-access devices (such as 
disk drives) or on sequential-access devices (such as communications 
interfaces) ; files on the Apple I M's built-in disk drive are accessed in exactly 
the same manner as files on a large remote hard-disk drive. SOS lets you 
perform simple operations on files (such as read, write, rename) that are 
actually complex operations on the devices that store your information. 
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SOS uses a hierarchical structure of directories and subdirectories to 
expedite file access. As described in the Apple III Owner's Guide, related 
files can be grouped together in directories and subdirectories, and 
special naming conventions make it easier to specify groups of files. 

1.2.5 Devices 

The Apple III can support a variety of peripheral devices. Some of these 
devices are built into the Apple III itself; others must be plugged into 
peripheral interface connectors inside the Apple III. 

SOS supports operations on two types of devices: block devices and 
character devices. Block devices read and write blocks of 512 bytes in 
random-access fashion; character devices read and write single bytes 
in sequential-access fashion: both support the concept of a file to which 
you read and write single bytes. SOS defines the ways in which you can 
control and read the status of both kinds of devices. 

1.2.6 The 6502 Instruction Set 

The 6502 is the processor in both the Apple II and the Apple III, but in the 
Apple III its power is extended in two ways: 

• Additional hardware gives it two enhanced addressing modes, 
allowing it to address efficiently far more than 64K bytes 

of memory. 

• The BRK instruction is used to execute SOS calls. SOS calls can 
be thought of as an extension of the 6502 instruction set: that 

is, a set of 4-byte 6502 instructions that are emulated in software 
by the operating system. 
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This chapter describes the methods an interpreter uses to obtain and 
manipulate memory. The actual writing and construction of an interpreter 
is described in Chapter 7. 

2. 1 Addressing Modes 



Since the 6502's address bus is only 16 bits wide, it can directly address 
only 64K bytes. This is not enough memory for many of the applications 
the Apple III is intended for, so the Apple Ill/SOS system has been 
designed with new addressing techniques to allow you to efficiently 
access up to 51 2K bytes of memory. 

The Apple Ill's memory is subdivided into banks of 32K bytes each. The 
architecture of SOS can support up to 16 such banks, or a system with 
51 2K bytes. 

The current Apple III hardware supports up to eight banks, or 
256K bytes. 

Certain regions of memory are reserved for use by SOS and its device 
drivers; the rest is available for use by an interpreter and its data. 

Two methods are used to specify locations in the Apple Ill's memory: 

• bank-switched addressing, which specifies locations with a 
bank-plus-address form; and 

• enhanced indirect addressing, which specifies locations with 
a three-byte pointer form. 

2. 1. 1 Bank-Switched Memory Addressing 

The bank-switched method is the standard memory-addressing technique 
used to execute interpreter code; it can also be used for data access. In 
bank-switched addressing (see Figure 2-1), the 6502's addressing space 
is filled by two banks at a time. 



■ 

■ 
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Figure 2-1. Bank-Switched Memory Addressing 

One bank (called the "SOS bank", or S-bank) is always present. This 
unswitched bank occupies locations $0000 through $1 FFF and locations 
$A000 through $FFFF in the standard 6502 addressing space. The larger 
region contains SOS. The smaller region contains data areas used by 
SOS, as well as the interpreter's zero page and stack page, described in 
section 2.2.1. 

Locations $2000 through $9FFF are occupied by one of up to 15 
switchable banks, numbered $0 through $E. Normally, the highest bank in 
the system (bank $2 for a 128K system, bank $6 for a 256K system, bank 
$E for a 51 2K system) is switched into this space: this bank contains the 
interpreter But the interpreter can cause any of the other banks to be 
switched in, either to execute code or to access data. To switch another 
bank into the address space (see Figure 2-2), the interpreter changes the 
contents of the banl< register (memory location $FFEF), as explained in 
section 2.4.1. 
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Figure 2-2. Switching In Another Bank 

Locations within the S-bank or the currently selected bank may be 
specified by a two-byte address, notated here as four hexadecimal digits: 

$nnnn $0000 to $1 FFF S-Bank Address 

$2000 to $9FFF Current-Bank Address 

$A000 to $FFFF S-Bank Address 

where each n is a hexadecimal digit. This address uniquely identifies 
any location within the current address space. 

Locations in bank-switched memory (all banks but the S-bank) are 
specified by their four-digit address, plus the number of the bank they 
reside in. The addresses of these locations are in the form: 

$b:nnnn $0:2000 to $0:9FFF Bank-Switched 
$1 :2000 to $1 :9FFF Addresses 



$E:2000 to $E:9FFF 
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where $b is a hexadecimal digit from $0 to $E, and each n is a 
hexadecimal digit. 

Addresses in the current bank can be specified with or without 
the bank number: that is, in current-bank form or in bank- 
switched form. The addresses $E:2000 and $2000 are equivalent 
If bank $E Is switched in. 

Note that bank-switched address specifications such as $0:FFDF and 
$2:01 FF are not standard: these addresses, being in S-bank space and 
unaffected by bank-switching, are normally specified without the bank 
number 

Address Specifies 



$0:2000 First location in bank 

$2:9FFF Last location in bank 2 

$F:32A4 Invalid: there is no bank $F. 

$1 :B700 Non-standard: use S-bank specification $B700 

Table 2-1. Addresses in Bank-Switched Notation 



2. 1.2 Enhanced Indirect Addressing 

The second memory-addressing method, enhanced indirect addressing, 
uses a three-byte extended address to access each memory location. 
This method lets a program in one bank access data in other banks. 
Enhanced indirect addressing lets any 6502 instruction that allows 
indirect (-X or -Y) addressing to access data within any pair of adjacent 
memory banks. (For example, banks $0 and $1 , and banks $1 and $2, 
constitute bank pairs.) This addressing method is considerably more 
efficient than bank-switching, since the bank register need not be altered 
in order to access data in other banks. 

Enhanced Indirect addressing is used for data access only. 
Programs cannot execute In the memory space defined by this 
method. 
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An extended address specification consists of a two-byte address and 
one extension byte, or X-byte, which has no relation to the 6502's X 
register. The address is in standard 6502 form (low byte followed by 
high byte), and may be from $0000 to $FFFF, with some restrictions 
explained later The X-byte is of the form shown in Figure 2-3. 



Bit 



1 r 

unused 



Figure 2-3. X-byte Format 



Bit 7 of the X-byte is the enhanced-addressing bit, or E-bit; bits through 
3 are the bank-pair field, or Sfte/d. If the E-bit is0, normal indirect address- 
ing takes place, using the S-bank and current bank. If the E-bit is 1 , 
enhanced indirect addressing (see Figure 2-4) takes place, and the B field 
determines which of several bank pairs are mapped into the address space. 
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=avoicl 



Figure 2-4. Enhanced Indirect Addressing 



The X-byte selects one of up to 16 pairs of banks to fill the 64K memory 
space, and the two-byte address selects a specific location within the 
bank pair Extended addresses have this form: 
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$8x:nnrin $80:0100 to $80:FFFF Banks and 1 

$81:0100 to $81:FFFF Banks 1 and 2 



$8m:0100to$8m:7FFF Bankm 

$8F:0000 to $8F:FFFF S-bank and Bank 



where x and each n are hexadecimal digits, and m is the number of the 
highest switchable bank. 

Extended address notation differs from bank-switched address notation 
in the number of digits before the colon. An extended address begins 
with a two-digit X-byte, whose first digit is always $8; a bank-switched 
address begins with a one-digit bank number 



The X-byte can range from $80 (banks and 1) to $8m (bank m), where 
m is the number of the highest bank: $2 for a 128K system; $6 for a 256K 
system; or $E for a 51 2K system. The highest bank pair is not really a pair: 
it ends at $8m:7FFF, and higher addresses will produce undefined results. 
The X-byte has a singular value, $8F, which pairs the S-bank with bank $0 
(see hand paragraph below). 

Note that the addresses $8n:0000 to $8n:00FF are not accessible 
via enhanced indirect addressing. Any reference to these 
addresses will give you a location on the currently selected zero 
page. To address these locations ($8n:0000 to $8n:00FF) you 
can use the equivalent address in the next-lower bank pair: that 
is, $8(n-1):8000 to $8(n-1 ):80FR (See fourth example below). 
This trick does not work for the addresses $80:0000 to $80:00FF: 
for these addresses, you can use the equivalent addresses 
$8F:2000 to $8F:20FF (see hand, below). 



In addition, the addresses $8n:FF00 through $8n:FFFF should generally 
be avoided, as indexing these addresses by the value in the Y-register 
may cause a carry and produce an address in the range $8n:0000 
through $8n:00FF— this address is on the zero page. The locations 
$8n:FF00 through $8n:FFFF may be addressed with the equivalent 
addresses in the next-higher bank pair: that is, $8(n+1):7F00 through 
$8(n+1):7FFF 
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The invalid and risky regions are shown in color in Figure 2-4. 
Address Specifies 



$80:8000 First location in bank $1 

$81 :7FFF Last location in bank $1 

$03:221 5 Not an extended address: X-byte ignored 

$81:002E Invalid: use $80:802E 

$81:FF2E Risky: use$82:7F2E 

Table 2-2. Extended Addresses 

The X-byte $8F is unique: it causes the S-bank and bank $0 to be 
switched into the 6502's address space in their standard bank- 
switched arrangement. Bank $0 is mapped to the locations 
$8F:2000 to $8F:9FFF, so no part of it conflicts with the zero 
page. The X-byte $8F Is used primarily by graphics device drivers 
to access the graphics area at the bottom of bank $0. (See the 
eye paragraph In section 2.4.2.2.) 




2.2 Execution Environments 



An Apple III program's execution environment defines the state of the 
machine while that program is running. The two major programs, SOS 
and your interpreter, run in different environments; assembly-language 
modules run in an environment much like the interpreter environment; 
and device drivers run in part of the SOS environment. 

The environment defines the location of the program being executed, 
the location and type of memory that program can access, the processor 
speed, and the kinds of interrupts the program can handle. (Interrupts are 
explained in Chapter 6 and in the Apple III SOS Device Driver Writer's 
Guide.) The environment also determines whether and how one program 
can communicate with another. The environment also specifies which 
zero page and stack the executing program will use, as explained in the 
next section. 
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2. 2. 1 Zero Page and Stack 

The 6502 microprocessor reserves the first two pages in memory for 
special access. The zero page (locations $0000 through $00FF) is used 
by several 6502 addressing modes for indirect addressing and to save 
execution time and code space. 

But the zero page has only 256 locations, and if both the interpreter and 
SOS are trying to save data in that page, it quickly fills up. The Apple 1 1 1 
resolves this contention by allocating separate zero pages to the 
interpreter ($1 A00 through $1 AFF) and SOS ($1800 through $18FF). 
Thus when an interpreter accesses a zero-page location (by executing 
an instruction followed by a one-byte address), it's accessing an area 
of memory completely separate from the zero-page storage of SOS. 

Similarly, page one (locations $0100 through $01 FF) is used as a 256- 
byte push-down stack for temporary data storage and subroutine and 
interrupt control. Programs that call many nested subroutines and save 
many temporary values on the stack can quickly fill it up. Again, the 
Apple III resolves this contention by allocating separate stacks to the 
interpreter ($1 B00 through $1 BFF) and to SOS ($0100 through $01 FF). 

Each zero page and stack is accessible from other environments as a 
different page in memory. The SOS kernel, for example, can access 
locations in the interpreter's zero page by using the addresses $1 A00 
through $1AFF 

An Interpreter should access only Its own zero page and stack. 
An interpreter that writes into the SOS zero page or stack will 
generally come to an untimely and untidy end. 
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2.2.2 The Interpreter Environment 

The interpreter is in the highest switchable bank of memory (bank $n): 
for a 128K system, this would be bank $2; for a 256K system, bank $6; 
for a 51 2K system, bank $E. Figure 2-5 shows the interpreter placement 
in memory. 



interpreter 



\$2000 

. last 
bank 



/ 



$A000 



$FFFF 



Figure 2-5. Interpreter Memory Placement 

An Interpreter shorter than 6K bytes is located entirely in 
locations $A000 through $B7FF of the S-bank. An interpreter 
longer than 6K ($1800) bytes begins in the highest bank (the 
first byte Is between $n:$2000 and $n:$9FFF), and ends In the 
S-bank (the last byte is at location $B7FF). For example, an 
Interpreter that is 10K ($2800) bytes long in a 128K system would 
reside from $2:9400 to $B7FF 

Although the maximum size of an interpreter is 38K ($9800) bytes, we 
recommend that interpreters be restricted to 32K ($8000) bytes, for 
compatibility with future versions of SOS. A longer interpreter can be 
split up into a main unit and one or more separately-loaded modules. 
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An interpreter runs at a nominal 2 MHz clock rate. In practice, execution 
speed is approximately 1 .4 MHz if the Apple Ill's video display is on; 
turning off the video display (using the .CONSOLE driver's CTRL-5 
command) raises execution speed to 1 .8 MHz. (The remaining 0.2 MHz is 
consumed by memory refresh.) An interpreter must be fully interruptable, 
so no timing loop in an interpreter will be reliable, except to provide a 
guaranteed minimum time. 

The interpreter's zero and stack pages, always accessible by normal 
zero-page and stack operations, can also be addressed as pages $1 A and 
$1 B. Page $1 6 is used as the extension page for enhanced indirect 
addressing (see section 2.1 .2). 



Environment Attribute Setting 




IRQ Interrupts Enabled 

NMI Interrupts Enabled or Disabled 

Processor Speed Full speed 

Zero Page Page $1 A 

Stack Page Page $1 B 

Extend Page Page $16 

Bank Highest 

Table 2-3. Interpreter Environment 



Of the above environment attributes, only the bank register 
(location $FFEF) should be changed by an Interpreter 
Adherence to this rule is essential for correct system operation. 



An assembly-language module operates in the same environment as the 
interpreter, except that it may reside in a different bank (see section 7.4). 
An assembly-language module must share the interpreter's zero page 
and stack. 



2.2.3 SOS Kernel Environment 

The SOS kernel (SOS without its device drivers) resides in the upper 
regions of S-bank memory, and uses the lower areas of the S-bank for 
data and buffer storage (see Figure 2-6). 
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Figure 2-6. SOS Kernel Mennory Placement 
The SOS kernel uses no bank-switched memory. 

SOS uses its own zero page and stack (pages $18 and $01 , respectively). 
It can be interrupted by both IRQ and NMI interrupts. 

Environment Attribute Setting 



IRQ Interrupts 
NMI Interrupts 
Processor Speed 
Zero Page 
Stack Page 
Extend Page 
Bank 



Enabled 
Enabled 
Full speed 
Page $18 
Page $01 
Page $14 
S-bank 



Table 2-4. SOS Kernel Environment 



2.2.4 SOS Device Driver Environment 

Device drivers are placed directly below the interpreter (that is, in memory 
locations with smaller addresses), in the highest-numbered bank in the 
system (see Figure 2-7). Any drivers that do not fit into that bank are 
placed in the next lower bank, beginning at $9FFF and moving down to 
lower-numbered addresses. 
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Figure 2-7. SOS Device Driver Memory Placement 

Drivers share the SOS zero page and stack. A driver must reserve space 
within itself for all buffers that it uses: it cannot claim any memory outside 
itself. 

Environment Attribute Setting 



IRQ Interrupts 
NMI Interrupts 
Processor Speed 
Zero Page 
Stack Page 
Extend Page 
Bank 



Enabled or Disabled 

Enabled or Disabled 

Full Speed or Fixed 1 MHZ 

Page $18 

Page $01 

Page $14 

Interpreter's or Lower 



Tabie 2-5. SOS Device Driver Environment 



A device driver can alter the execution speed; it can disable interrupts for 
up to 500 microseconds to run timing loops: for more information, see the 
Apple III SOS Device Driver Writer's Guide. 
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2.2.5 Environment Summary 

The environment determines what actions a program can perform and 
what other programs it can communicate with. The following table 
summarizes the capabilities of each environment. 

Function Interpreter* Kernel Driver 



Can perform a SOS call 


Yes 


No 


No 


Can call SOS subroutines 


No 


Yes 


Yes 


Can be interrupted 


Yes 


Yes 


Yes** 


Can respond to IRQ 


No 


Yes 


Yes 


Can respond to NMI 


No 


Yes 


No 


Can disable interrupts 


No 


Yes 


Yes 


Can detect and queue an event 


No 


Yes 


Yes 


Can respond to an event*** 


Yes 


No 


No 


Can access interpreter memory 


Yes 


Yes 


Yes 


Can access free memory 


Yes 


Yes 


Yes 



* An assembly-language module runs in the same environment as its interpreter 

" A device driver can contain a special section, called an interrupt handler, designed 
specifically to handle IRQ interrupts. 

*** Events, or software interrupts, are defined in Chapter 6. 

Table 2-6. Environment Summary 
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2.3 Segment Address Notation 



When an interpreter is loaded into memory, it occupies part of the S-bank 
and part of the highest-numbered bank. The region below the interpreter 
is occupied by the device drivers; the region below the drivers is free 
memory, as shown in Figure 2-8. 
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Figure 2-8. Free Memory 

The interpreter has access to its own space. If it needs more memory, it 
can gain access to free memory by using the SOS memory calls. These 
calls use segment address notation, to define segments of memory for 
allocation (see Figure 2-9). Segment address notation resembles bank- 
switched address notation, except that it defines addresses of segments, 
not bytes, of memory in either the S-bank or a switchable bank. A page is 
a group of 256 contiguous bytes with a common high address byte. A 
segment is a set of contiguous pages. The lowest page in a segment is 
called the base; the highest page is called the limit. Each bank of memory 
contains 128 pages, numbered $20 through $9F. 
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Figure 2-9. Segment Address Notation 

Each page of memory has a corresponding segment address, which is 
very similar to that page's starting address in bank-switched memory. 
The format is: 



$bb:pp 



$00:20 to $00:9F Segment 
$01 :20 to $01 :9F Addresses 



$0E:20 to $0E:9F 

where bb is the bank number (one byte) and pp is the page number 
(one byte) in that bank. Notice that for segment addresses in bank- 
switched memory the page part of the segment address is always between 
$20 and $9F. 

Segment Address Specifies 



$01:30 
$04:62 
$00:9F 



Page beginning at $01 :3000 
Page beginning at $04:6200 
Page beginning at $00:9F00 



Table 2-7. Addresses in Segment Notation 



A segnnent address specifies an entire page, not just the first 
location in that page. A base segment address and a limit 
segment address together specify a segment. 
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Segment addresses can also specify pages in S-bank memory: the format 
then is slightly different. For segments in the lower part of the S-bank, 
the bank part of the segment address is always $0F; for segment addresses 
in the upper part of the S-bank, the bank part of the segment address is 
always $10. In either case, the page part (as above) is the same as the 
high byte of the memory address. 

$bb:pp $0F:00to$0F:1F Segment 

$10:A0to$10:FF Addresses 

Segment Address Specifies 



$0F:14 Page beginning at $1400 

$0F:02 Page beginning at $0200 

$10:B8 Page beginning at $B800 

Tabie 2-8. Addresses in Segment Notation, S-Bank 

Before segment addresses can be used by an interpreter, they must be 
converted into bank-switched or extended addresses. These conversions 
are explained in section 2.4.3. The SOS memory calls that use segment 
addresses are explained below. 



2.3.1 Memory Calls 

interpreters use these SOS calls to allocate and release memory. 
The name of each call below is followed by its parameters (in boldface). 
The input parameters are directly-passed values. The output parameters 
are all directly-passed results. The SOS call mechanism is explained 
in Chapter 8; the individual calls are described fully in Chapter 1 1 of 
Volume 2. 

REQUEST_SEG 

[base, iimit, seg id: value; seg num: result] 

This call requests the allocation of the contiguous region of memory 
bounded by the base and limit segment addresses. A new segment is 
allocated if and only if no other segment currently occupies any part of 
the requested region of memory. If a segment is allocated, an entry for 
it is made in the segment table. 
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FIND_SEG 

[search mode, segjd, pages: value; pages, base, limit, seg num: result] 

This call searches memory from the highest memory address down, until 
the first free space of length pages that meets the search restrictions in 
search_mode is found. If such a space is found, this free space is allocated 
to the caller as a segment (as in REQUEST_SEG): both the segment 
number and the location in memory of the segment are returned. If a 
segment with the specified size is not found, then the size of the largest 
free segment which meets the given criterion will be returned in pages. In 
this case, however, error SEGRQDN will be returned, indicating that the 
segment was not created. 

CHANGE_SEG 

[seg num, change mode, pages: value; pages: result] 

This call changes either the base or limit segment address of the specified 
segment by adding or releasing the number of pages specified by the 
pages parameter. If the requested boundary change overlaps an adjacent 
segment or the end of the memory, then the change request is denied, 
error SEGRQDN is returned, and the maximum allowable page count is 
returned in the pages parameter 

GET_SEG_INFO 

[seg num: value; base, limit, pages, seg Jd: result] 

This call returns the beginning and ending locations, size in pages, and 
identification code of the segment specified by seg_num. 

GET_SEG_NUM 

[seg address; value; seg num: result] 

This call returns the segment number of the segment, if any, that 
contains the segment address. 
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RELEASE_SEG 
[seg_num: value] 

This call releases the memory occupied by segment seg_num by 
removing the segment from the segment table. The memory space 
formerly occupied by segment seg_num can now be allocated to another 
program. If seg_num equals zero, then all non-system segments (those 
with segment identification codes greater than $0F) will be released. 

2.4 Memory Access Techniques 



The Apple III augments the eleven addressing modes of the 6502 in two 
ways: bank-switching and enhanced indirect addressing. Bank-switched 
addressing is used for executing code segments residing in bank- 
switched memory. Enhanced indirect addressing is used for access to 
data in memory. These techniques give your programs efficient access 
to all of memory. 

In addition, SOS uses segment address notation to allocate free memory 
for programs. Segment address notation is reserved for the SOS memory 
management calls, which the interpreter uses to obtain and release 
memory. 

This section discusses the most common modes of access to program 
and data storage areas in the Apple III. It shows how the memory 
addressing methods introduced in section 2.1 and 2.3 are used in 
performing various operations, and how these methods can be used 
in a program. It also presents sample algorithms that convert the address 
of a location from one form to another 

2.4. 1 Subroutine and Module Addressing 

The 6502's JMP and JSR instructions affect the flow of control within 
an interpreter As the interpreter resides in the S-bank and the highest 
switchable bank, the destination for these instructions is specified in 
S-bank or current-bank notation. The JSR and JMP instructions should 
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be used in the normal 6502 absolute addressing mode. Here are three 
examples of such instructions. 

AA401 4C 3A85 JMP 853A ; Jump to location $853A 

; in interpreter 

8B801 20 5022 JSR 2250 ; Jump to subroutine at 

; location $2250 

23BB|4C52B6 JMP 0B652 ; Jump to location $B652, 

; in the S-bank 

All assembly-language listings in this manual were made with 
the Apple 1 1 1 Pascal Assembler This is the only assembler 
supported for the Apple 1 1 1 . 

If an interpreter wishes to transfer control to a module residing in another 
bank, the normal addressing mode will not work: the interpreter must 
switch in the proper bank before performing the JMP or JSR. 

Bank-switching can be performed only by code residing In 
S-bank (that is, unswitched) memory. An interpreter that 
performs bank-switching should use a single dispatching 
routine, located between locations $A000 and $B7FF in the 
S-bank, for all bank-switching. 



The interpreter switches in a given bank by storing the number of the bank 
in the bank register (location $FFEF). Once this is done, the JMP or JSR 
instruction can be executed normally. Here's a valid jump: 



00001 FFEF BREG .EQU 0FFEF ; Define bank register 

A05OI A9 01 LDA #01 ; Jump to location $1 :326B 

A052I 8D EFFF STA BREG 

A055I4C6B32 JMP 326B 

Here's a jump into oblivion: 

00001 FFEF BREG .EQU 0FFEF ; Define bank register 

8B40IA902 LDA #00 ;This program will crash, 

8B42I 8D EFFF STA BREG ; as it is not located 

8845140 4440 JMP 4044 ; in the S-bank. 
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The module, once switched-in, can use current-bank addresses to 
jump around inside itself, and can JMP or RTS back to the part of the 
interpreter in S-bank memory, without bank-switching. The interpreter 
must, however, switch the highest bank back in before any interpreter 
code below S-bank memory can be executed. To do this the interpreter 
must save its own bank number before calling the module. The interpreter 
can read the contents of the bank register to find the number of its bank, 
then call a module and, upon returning, restore the proper bank. The 
following subroutine demonstrates how an interpreter would call a 
module located at $1 :3300. 



00001 FFEF BREG 


.EQU 


0FFEF 


Define bank register 


A700I AD EFFF 


LDA 


BREG 


Get the current bank 


A703I 48 


PHA 




Save it on the stack 


A704I A901 


LDA 


#01 


Switch in 


A706I 8D EFFF 


STA 


BREG 


bank $1 


A709I 200033 


JSR 


3300 


Call the module 


A70OI 68 


PLA 




Upon return, restore 


A70D|8D EFFF 


STA 


BREG 


the bank number. 


A710I 60 


RTS 




Return to main code. 




Only the lower four bits of the bank register contain the current bank 
number; the upper four bits should be zero. 



2.4.2 Data Access 

An interpreter can access data in three places: 

• In the interpreter's zero page; 

• In a table within the interpreter itself; 

• In a segment allocated from free memory. 

Data can be accessed in locations $0000 through $00FF, the interpreter's 
zero page, by instructions in absolute, zero-page, or zero-page indexed 
mode. For example, 



6BA7|A554 LDA 54 ; Value on zero page 

747FI8DE300 STA 00E3 ; Also on zero page 



To access data in a table within itself, the interpreter must use the 
absolute address of the table (in current-bank or S-bank notation) in 
absolute or indexed addressing mode. 



70751 CD9BAB 



585DI BD5022 



CMP 0AB9B 



LDA 2250,X 



Compare location $AB9B 
to accumulator 

Load accumulator from 
byte $2250 + X 



Data in free memory can be accessed by an interpreter in two ways: by 
bank-switching or by enhanced indirect addressing. All data used by an 
interpreter must be stored in SOS-allocated segments (see section 11 .1 of 
Volume 2). To begin storing data in free memory, an interpreter must first 
request a segment of free memory from SOS, using a REQUEST_SEG or 
FIND_SEG call. SOS will return a segment address, which the interpreter 
can change into an address more suitable for data access. Conversion 
algorithms are described in section 2.4.3. 



2.4.2. 1 Bank-Switched Addressing 

Bank-switching for data access operates just like bank-switching for 
module execution (described in section 2.4.1). To perform an operation 
on location $b:nnnn, store $b in the bank register and perform the 
operation on absolute location $nnnn. For instance. 



00001 FFEF 


BREG. 


.EQU 


0FFEF 


Define bank register 


00001 




.ORG 


0A3AA 


Code starts here 


A3AAI AD EFFF 




LDA 


BREG 


Save current bank register 


A3ADI 48 




PHA 






A3AEI A000 




LDY 


#00 


Perform a loop to 


A3B0I 8C EFFF 




STY 


BREG 


zero all locations 


A3B3I 98 




TYA 




from $0:9800 to 


A3B4I 990098 


LOOP 


STA 


9800,Y 


$0:98FF 


A3B7I C8 




INY 






A3B8I D0 FB 




BNE 


LOOP 




A3BAI 68 




PLA 




Store bank register 


A3BBI 8D EFFF 




STA 


BREG 





Programs and Memory 31 



Just as in module execution, the code to perform bank-switched data 
access must reside in the part of the interpreter that is located in S-bank 
memory, and you must remember to restore the original contents of the 
bank register before returning to the main part of the interpreter 

2.4.2.2 Enhanced Indirect Addressing 

Enhanced indirect addressing allows an interpreter to access any location 
in bank-switched memory without having to switch in the proper bank 
and then switch back. Any 6502 instruction that supports indirect-X or 
indirect-Y addressing (ADC, AND, OMR EOR, LDA, ORA, SBC, STA) can 
use enhanced indirect addressing. 

To perform a normal (not enhanced) indirect operation on location 
$hilo, you store $/o in a location $nn on zero page, and store $hi in the 
following location. You must also store $00 in location $nn+1 of the 
X-page: the $00 turns off extended addressing. Then you perform the 
operation in an indirect mode on location $nn. The two bytes at $nn 
are a pointer: you can increment, decrement, and test them to move the 
pointer through your data structure. 

Enhanced indirect addressing merely adds one step to this process. To 
perform an enhanced indirect addressing operation, in the interpreter 
environment, on location $xx:hilo, you store $/o in $nn, $/?/ in $nn+1, 
and $xx in location $16nn+^ . Then perform the operation in an indirect 
mode on location $nn. The location $16nn+^ is the extension byte, or 
X-byte, of the pointer 

Enhanced indirect addressing takes effect whenever you execute an 
indirect-mode instruction and bit 7 of the pointer's extension byte (X-byte) 
is 1 : that is, whenever the extension byte is between $80 and $8F If you 
wish to perform normal indirect operations, using bank-switched 
addressing rather than enhanced indirect addressing, you should store 
your pointer in bank-switched form in the zero page, and set its extension 
byte to $00, which will make sure bit 7 is 0. For instance. 
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61EEI A9 89 


LDA 


#89 


; Perform a LDA $82:3289 


61F0I8557 


STA 


57 


; To set up, first put 


61F2I A932 


LDA 


#32 


; $lohi in zero page 


61F4I 8558 


STA 


58 


; locations $57 and $58; 


61F6I A982 


LDA 


#82 


; then put $xx into 


61F8I8D 5816 


STA 


1658 


; location $1658. 


61 FBI A0 00 


LDY 


#00 


; Index by0. 


61FDI B1 57 


LDA 


(57),Y 


; Perform the operation. 



Once the three bytes are stored, you can manipulate them almost as 
easily as a two-byte pointer, and you can use one pointer to access data 
in all 15 switchable banks (a total of 480K). This makes it easy to handle 
large data structures. 



Remember that enhanced indirect addressing is different from 
bank-switched addressing. For a description of the two 
methods, see section 2.1 . 

If you are using the enhanced indirect-Y addressing mode and 
are using the Y-register to index from an extended address, we 
strongly recommend that you avoid using addresses $8n:FF00 
through $8n:FFFF. Adding a Y value to one of these addresses 
may cause a carry and create an address in the range $8n:0000 
through $8n:00FF, which will access a location on the zero 
page. If you keep your pointer below $8n:FF00 whenever you 
are using a non-zero Y register in the enhanced indirect-Y 
addressing mode, you will avoid this problem. 




2.4.3 Address Conversion 



Most interpreters deal mainly with addresses in segment and extended 
form: bank-switched addresses are used only when an interpreter must 
execute code in a different bank. But bank-switched addresses are a 
convenient intermediate form between segment and extended addresses 
they can tje readily converted to either of the other forms. 



The following algorithms describe the basic conversions between 
addresses in segment, bank-switched, and extended forms. 
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2.4.3. 1 Segment to Bank-Switched 

A segment address specifies a page in bank-switched memory. 
When you convert a segment address to a bank-switched 
address, the result is the address of the first byte in that page. 

To convert a segment address $bb:pp to a bank-switched address 
$B:NNNN, 

if (bb = 0F)or(bb = 10) 

then B := 

else B := bb; 
NNNN := pp00 

For example, the following segment and bank-switched 
addresses are equivalent. 

Segment Bank-Switched 

$04:63 = $(4): (6300) = $4:6300 

$07:89 = $(7):(8900) = $7:8900 
$10:1 F = $(0):(1F00) = $0:1 F00 

The bank part, bb, of the segment address is converted to $0 if it indicates 
the S-bank, or truncated if it indicates any other bank. It then becomes 
the bank part of the bank-switched result. The page part, pp, of the 
segment address becomes the high part of the bank-switched address, 
and the low part is set to $00. 

2.4.3.2 Segment to Extended 

When converting to extended form, you must be careful to make 
sure that the result is in the valid range of extended addresses. You 
must also handle the special cases of S-bank segment addresses 
and the segment address $00:20. 
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To convert a segment address $bb:pp into an extended address 
$XX:NNNN, 



if ( (bb = $00) {zerobanl<} 
or (bb = $0F) {low S-bank} 

or(bb = $10) ) {high S-bank} 

then 
begin 
XX :=$8F ; 
NNNN := pp00 
end 

else {general case} 

begin 

XX :=$80+bb-1 ; 
NNNN := pp00+$6000 
end; 



For example, the following segment and extended addresses are 
equivalent: 



Segment Extended 



$09:2A = $(80+9-1 ):(2A00+6000) - $88:8A00 
$02:94 = $(80+2-1): (9400+6000) = $81:FF00 
$0F:1E = $(8F):(1E00) = $8F:1E00 

If the segment address specifies a page in S-bank memory, the bb part is 
ignored, and the pp part is converted to the address of the beginning of a 
page in the S-bank/bank pair of the enhanced indirect addressing space. 

If the segment address is in bank-switched memory, the bb part is 
converted to the xx byte that selects a bank pair with the specified bank 
in the top half of the pair The pp part is then converted to the address of 
the beginning of the proper page in that bank pair 



2.4.3.3 Extended to Bank-Switched 



When changing an extended address to bank-switched form, you must 
handle the special case of an S-bank extended address. You must also 
determine whether the extended address points to a location within the 
upper or lower bank in its bank pair 
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To convert an extended address $xx:nnnn to a bank-switched 
address $B:NNNN, 

if (XX = $8F) then 
begin 
B := $0 ; 
NNNN := nnnn 
end 
else 

if (nnnn < $8000) then 
begin 

B := xx-$80 ; 

NNNN :=nnnn+$2000 
end 
else 
begin 

B := xx-$80+1 ; 

NNNN := nnnn-$6000 
end; 

For example, the following extended and bank-switched addresses 
are equivalent: 

Extended Bank-switched 



$86:4365 = $(86-80): (4365+2000 = $6:6365 
$82:EFB4 = $(82-7F):(EFB4-6000) = $3:8FB4 
$8F:2000 = $($0):(2000) = $0:2000 

If the extended address refers to a location in the S-bank, the bank part of 
the bank-switched address is set to $0 and the address part is used 
directly. 

If the extended address refers to bank-switched memory, then the xx part 
specifies a bank pair If the address part is less than $8000, the extended 
address refers to a location in the lower bank in the pair; otherwise, it 
refers to a location in the upper bank. The bank part is set to the bank 
number, and the address part is adjusted to the proper location within 
the specified bank. 
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2.4.4 Pointer Manipulation 

Most data structures you use are accessed by three-byte pointers in 
extended-address form. Tfie preceding section described how to create 
an extended-address pointer from a segment address; this section 
describes how to increment and test such a pointer. 

These algorithms are designed for ease of explanation, not for efficiency. 
They work, but are not intended to be incorporated verbatim into real 
applications. 




2.4.4. 1 Incrementing a Pointer 



An increment operation defines successive values of a pointer, and thus 
traces a path through successive locations in memory (see Figure 2-10). 
This path covers all switchable banks, but omits the S-bank. The path 
traced by the algorithm below begins at the first location in bank 0, 
extended address $8F:2000. It continues through the first page in this 
bank, then proceeds to the second page in the same bank with the 
extended address $80:0100. This path is chosen to avoid the invalid 
address range $80:0000 to $80:00FF. 



$2000 
$2FFF 



$A000 



$FFFF 



S0100 



$7F00 



$FEFF 
$FFFF 



$0100 



$7F00 
$8000 



SFEFF 
$FFFF 



$0000 
$0100 



$7F00 



SFEFF 
$FFFF 



X-byte = $8F X-byte = $80 X-byte = $81 



X-byte = $8D 



Figure 2-10. Increment Path 



The path then continues through the last location in bank 1 , extended 
address $80:FFFF The path switches to the next bank pair and continues 
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with the first location in bank 2, $81 :8000. The path continues in this 
manner to the last location in the last bank in memory, at which point 
it terminates. 

The following algorithm increments an extended address $xx:nnnn. 



repeat 

nnnn := nnnn +1 ; 

if (XX = $8F) and (nnnn > $20FF) 
then begin 

XX := $80 ; 

nnnn : = nnnn-$2000 
end; 

if ( nnnn>$FEFF) 
then begin 
nnnn := nnnn-$8000 ; 
XX := XX + 1 
end; 
until XX >$8D; 



{Move to next location. } 

{If beyond location $8F:2100, } 

{move to location $80:0100 } 

{If near end of a bank pair, } 

{switch to middle } 

{of next bank pair } 

{If no next pair, then stop. } 



Notice how this algorithm switches from one bank to the next when 
its address part reaches $FF00. This is to prevent the pointer from 
ever taking a value between $8n:FF00 and $8n:FFFF which can 
cause problems when used in an instruction in the indirect-Y 
addressing mode. 

2.4.4.2 Comparing Two Pointers 

Two pointers can be considered equal under three conditions. When 
you compare two pointers for equality, you must test ail three 
conditions. 

You can reduce the number of tests by comparing the two extension 
bytes first, then ordering the two numbers according to their 
extension bytes if they are unequal. 

The following algorithm compares $xx:nnnn to $XX:NNNN for 
equality, assuming that xx <=XX. 
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if ( ( (xx = XX ) and (nnnn = NNNN ) ) {1} 

or ( (XX = XX-1 ) and (XX <> $8F) and (nnnn = NNNN + $8000) ) {2} 
or ( (XX = $00 ) and (XX = $8F) and (nnnn = NNNN - $2000) ) ) {3} 

then equal : = true 

The three conditions are as follows: 

{1} The two pointers are expressed identically; 

{2} The two pointers are expressed in terms of adjacent bank pairs; 

{3} The first pointer is expressed in bank-switched form, and the second 
is expressed in extended form. 

Note that without the preliminary sorting of the two pointers according 
to their extension bytes, two more cases (a total of 8 more byte 
comparisons) are necessary to test for equality. 

2.4.5 Summary of Address Storage 

Addresses in the three forms given above are stored in memory in 
these ways: 

• S-bank and current bank addresses are stored in normal 6502 
style: as two consecutive bytes, low byte followed by high byte. 
Heed the warnings on bank-switched addressing given in section 
2.4.1. 

• Segment addresses point to pages and are stored as two 
consecutive bytes, bank part followed by page part. 

• Extended addresses are stored in the zero page and X-page. The 
address is stored in the zero page as two consecutive bytes, low 
byte followed by high byte. The X-byte is stored in the X-page 
(page $0F:16, in the interpreter environment) at the byte position 
parallel to the high byte of the address in zero page. An extended 
address is referred to by the location of the low byte of the 
address part: for instance, the pointer at location $0050 has its 
low part at $0050, high part at $0051 , and X-byte at $1651 ( in 
the interpreter environment). 
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3. 1 Devices and Drivers 



A device is a part of the Apple III, or a piece of external equipment, that 
can transfer information into or out of the Apple III. Devices include the 
keyboard and screen, disk drives, and printers. 

Devices provide the foundation upon which the SOS file system is 
constructed. In general, your program will talk to devices only through 
the SOS file system. 

3. 1. 1 Block and Character Devices 

SOS recognizes two kinds of devices: character devices and block 
devices. A character device reads or writes a stream of characters, one 
character at a time: it can neither skip characters nor go back to a 
previous character A character device is usually used to get information 
to and from the outside world: it can be an input device, an output device, 
or an input/output device. The console (screen and keyboard), serial 
interface, and printer are all character devices. 

A block device reads and writes blocks of 512 characters at a time; it can 
access any given block on demand. A block device is usually used to 
store and retrieve information: it is always an input/output device. Disk 
drives are block devices. 

3.1.2 Physical Devices and Logical Devices 

A physical device is a physically distinct piece of hardware: if an external 
device, it usually has its own box. A logical device is what SOS and the 
interpreter regard as a device: it has a name. For example, the keyboard 
and the screen are separate physical devices; but SOS regards them 
as one logical device — the console. On the other hand, if a disk drive 
contained two disks, each could be a separate logical device. 



I 
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3. 1.3 Device Drivers and Driver Modules 

Programs called device drivers provide the communication link between 
the SOS kernel and input/output devices: they take the streams of 
characters coming from SOS and convert them to physical actions of the 
device, or convert device actions into streams of characters for SOS to 
process. Device drivers for the standard Apple III devices are included in 
the SOS.DRIVER file: you can change or delete these, or add new ones, 
by using the System Configuration Program (SOP) option on the Utilities 
disk , as explained in the Apple III Owner's Guide and the Apple III 
Standard Device Drivers Manual. 

The Disk III driver is included in the SOS.KERNEL file. It cannot 
be removed or changed by the user, except to specify the number 
of drives in the system. 

Each logical device connected to the system has its own device driver: 
SOS can access the logical device through its driver Related device 
drivers, such as drivers for separate logical devices on one physical 
device, can be grouped into a driver module. The drivers in a module can 
share code or system resources, such as interrupt lines. A driver module 
must be configured into the system as a package: unneeded drivers 
cannot be deleted from it. Each driver in the module is named separately. 

The SOS kernel and the interpreter only deal with logical devices 
and their drivers. Whether the logical device is one physical 
device, several physical devices, or part of a physical device, is 
academic to the interpreter writer: it is only necessary to know 
that all three cases are possible. Similarly, SOS and the interpreter 
communicate with a device driver In precisely the same way 
whether or not the driver Is part of a driver module. 



3.1.4 Device Names 

A logical device and its driver are both identified by a device name. 
If a driver module has several drivers, each has a different device name, 
by which it can be separately addressed. The driver module itself has 
no name, as it is never addressed as such. (The SOP refers to a module 
by the name of the first driver in it.) 



A device name is up to 15 characters long: the first is a period; the second 
is a letter; the rest can be either letters or digits, in any combination (see 
Figure 3-1). 





letter 






( 





letter 



digit 



Figure 3-1. Device Name Syntax 
Some legal device names are 
.D1 

.PRINTER 
.BLOCKDEVICE 



Some illegal device names are 



PRINTER 
.BLOCK.DEVICE 
.BLOCK DEVICE 
.BLOCK/DEVICE 



(the first character is not a period) 
(only the first character can be a period) 
(a device name cannot contain a space) 
(a device name cannot contain a / ) 



A logical block device also has a volume name, discussed in section 
4.1 .3.2, which is the name of the medium (for example, a flexible disk) in 
the device. In general, the volume name, rather than the device name, 
should be used for communicating with the device. 
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3.2 The SOS Device System 



Since SOS accesses all devices through their drivers, the devices can be 
organized as a single-level tree, as illustrated by Figure 3-2): 



character 
device 




character 
device 



Figure 3-2. The SOS Device System 



This system of devices underlies the system of files that will be developed 
in the next chapter 



3.3 Device Information 



Certain information about a logical device and its driver is stored in 
the driver's Device Information Block (DIB), which is broken into the 
DIB header and the DIB configuration block. The header contains 
information that SOS uses to distinguish between block and character 
devices and between devices in each class. It can be read by the 
GET_DEV_NUIVI and D_INFO calls, but cannot be changed. The 
configuration block contains data that can be changed by the SCR such 
as the baud rate of a device. The size and contents of the configuration 
block differ for each device. Some information in the DIB header can be 
used only by SOS; the information that can be read by the interpreter is 
described below. 

devname and devnum 

A device name is up to 15 characters long: the first is a period; the second 
is a letter; the rest can be either letters or digits, in any combination. The 
device name can be changed only by the SCR 
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Linked with every device name is one and only one device number 
Access to information in the DIB is usually gained via the device 
number, which can be obtained from the device name through the 
GET_DEV_NUM call. Access to data stored or transmitted by a device 
is gained via the device name by accessing a similarly-named file, as 
explained in Chapter 4. 

slot_num and unit num 

A device can use an interface card plugged into one of the four peripheral 
interface connectors (called slots) inside the Apple III: such devices have 
a slot number, which indicates which of the four slots the card is plugged 
into. A device that does not use an interface card has a slot number of zero. 

Related device drivers can be grouped into a driver module: each such 
driver has a unit number that indicates the placement of that driver, and 
its device, in its group. Each driver in a driver module has a separate DIB, 
but the drivers may share code. For example, the formatter drivers on the 
Utilities disk have separate DIBs but share the same code: they can be 
called separately via their unit numbers. 

The SOS unit number has nothing to do with the logical unit 
number that the Apple III Pascal System assigns to devices. 

For more information about the internal operation of devices, see the 
Apple III SOS Device Driver Writer's Guide. 

devtype and sub_type 

Apple assigns two identifiers to each device indicating the device's 
functions. The device type lets you determine whether a given device 
is a printer, a communications interface, a storage device, a graphics 
device, or whatever; the device subtype distinguishes between devices 
of the same type (to separate letter-quality printers from line printers, 
for example). 

An interpreter that wishes to communicate with a certain type of device, 
but does not know the name or number of a device of that type, can 
examine these identifiers to find a suitable device. 




I 
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manufid and version_num 

Apple assigns two identifiers to each device and device driver: one to 
identify the manufacturer of the device and driver, and one to indicate 
their version number An interpreter can use these identifiers to ensure 
compatibility with different versions of the same device. 

totalblocks 

This field indicates the total number of blocks on a block device. 

If you wish a dev.type, sub.type, manuf_id, or version.num to be 

assigned to a device and driver, contact the Apple Computer 
PCS Division Product Support Department. This will ensure that 
the identifiers of each device and driver are unique and are 
available to interpreter-writers. 

3.4 Operations on Devices 



An interpreter can perform these operations on any device: 

• Find the device number associated with a given device name, 
using a GET_DEV_NUM call, orfind the device name associated 
with a given device number, using a D_INFO call; 

• Obtain the slot number, unit number, device type, device subtype, 
manufacturer's identification, and version number of a device, 
using a D_INFO call. 

An interpreter can perform these operations on a character 
device: 

• Receive device status information, using a D_STATUS call; 

• Send device control information, using a D_CONTROL call. 
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Using the System Configuration Program, you can 

• Add a new device to the system; 

• Remove a device from the system; 

• Alter the configuration block of a device; 

• Change the name, device type or subtype, or slot number of 
a device. 

See the Apple III Standard Device Drivers Manual, for information on 
device and control requests for specific devices, and the Apple III SOS 
Device Driver Writer's Guide for a complete specification on the 
SOS/driver interface. 

3.5 Device Calls 



The calls summarized below all operate on devices directly. The name 
of each call below is followed by its parameters (shown in boldface). 
The input parameters are directly-passed values and pointers to tables. 
The output parameters are all directly-passed results. The first list is of 
required parameters; the second, present only for D_INFO, is of optional 
parameters. The SOS call mechanism is explained in Chapter 8; the 
individual calls are described fully in Chapter 12 of Volume 2. 

D_STATUS 

[dev_num, status code: value; status_list: pointer] 

This call returns status information about the specified device by passing 
a pointer to a status list. The information can be either general or device- 
specific information. D_STATUS returns information about the internal 
status of the device or its driver; D_INFO returns information about the 
external status of the driver and its interface with SOS. 
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D_CONTROL 

[dev_num, control_code: value; control_list: pointer] 

This call sends control information to the specified device by passing a 
pointer to a control list. The information can be either general or device- 
specific information. D_CONTROL operates on character devices only. 

GET_DEV_NUM 

[dev_name: pointer; dev_num: result] 

This call returns the device number of the driver whose name is specified 
by dev_name. The file associated with the device need not be open. The 
device number returned is used in the D_READ, D_WRITE, D_STATUS, 
D_CONTROL, and D_iNFO calls. 

D_INFO 

[dev_num: value; dev name, optionjist: pointer; length: value] 

[slot_num, unit_num, dev_type, sub_type, 
total_blocks,manuf_id, version_num: optional result] 

This call returns the device name (and optionally, other information) 
about the device specified by dev_num. The file associated with the 
device need not be open. D_INFO returns information about the device's 
external status and interface to SOS; D_STATUS returns information 
about the internal status of the device and its driver. 
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4. 1 Character and Block Files 



A file is a named, ordered collection of bytes, used to store, transmit, or 
retrieve information. A file is identified by its name; a byte within the file 
is identified by its position in the ordered sequence. 

SOS recognizes two types of files: character files and block files. A 
character file is treated by SOS as an endless stream of characters, or 
bytes. SOS can read or write the current byte but cannot go back to a 
previous byte or forward to a later byte. A character file is an abstraction 
used to represent a character device. A character file can be read-only, 
write-only, or read/write, as determined by the device it resides on. A 
character file is identified by its device name, which is defined in the 
previous chapter. 

A block file is treated by SOS as a finite sequence of bytes, each one 
numbered. Any byte, or group of bytes, in a block file can be accessed 
by a call to SOS. A block file is so called because it resides in a volume 
on a block device: the volume is formatted into 512-byte blocks, also 
numbered. The blocks themselves are of concern only to SOS: the 
interpreter only reads or writes bytes. 

The interpreter need only ask for the particular bytes It wants, 
using the file READ and WRITE calls. SOS translates these 
byte-oriented calls into block-oriented device requests executed 
by the device driver. SOS moves the requested bytes between its 
I/O buffer and the interpreter's data buffer; the driver moves 
whole blocks containing these bytes to and from the I/O buffer. 
Device requests are described in the Apple III SOS Device Driver 
Writer's Guide. 



4. 1. 1 Structure of Character and Block Files 

Character and block files are quite different in implementation, but are 
treated similarly. In fact, sequential read and write operations are the 
same: an interpreter reads a sequence of bytes from its current position 
in a block file in the same way as it reads a sequence of bytes from a 
character file. 
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The bytes in a character file are not numbered and must be accessed 
sequentially. Each read or write operation can handle a single byte or a 
sequence of up to 64K bytes. The next operation starts where the last 
left off. Figure 4-1 shows the structure of a character file. 



current byte 



previous 
byte 



next 
byte 



Figure 4-1. Character File Model 

The bytes in a block file are numbered from $000000 up to $FFFFFE. 
A block file can contain up to 1 6,772,21 5 bytes (one less than 1 6 
Megabytes). Each read or write operation can handle a single byte 
or a sequence of up to 64K bytes. The next operation can start anywhere 
in the file, with no reference to the last. For this reason, a block file is a 
random-access file. Figure 4-2 shows the structure of a block file. 



mark 



EOF 



1 



Figure 4-2. Block File Model 



A block file's size is defined by its end-of-file marker, or EOF, which is 
the number of bytes that can be read from the file. The interpreter's place 
in the file is defined by the current position marker, or marit, which is the 
number of the next byte that will be read or written. 

Both of these may be moved automatically by SOS or manually by 
the interpreter. 
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4.1.2 Open and Closed Files 

A file can be open or closed: an open file can be read from or written to; 
a closed file cannot. 

Initially, a file is closed: access to a closed file is through its pathname, 
defined in section 4.2.3. 

When SOS opens a file in response to an OPEN call from an interpreter, 
SOS creates an access path to the file by placing an entry into the File 
Control Block (FOB), which is a table in memory containing information 
about all open files, and returns a reference number (ref_num) to the 
program that opened the file. This access path determines the way the file 
may be accessed (read from, written to, renamed, or destroyed). Every 
time that program accesses that file, it must use that access path and 
ref_num. Some files may have more than one access path, as shown in 
the Figure 4-3. 

Character File 



ref num = / 




re1_num = k 







.RS232 



Block File 



ref_num = m 
mark = p 



ref_num = n 
mark = q 




1 2 



Figure 4-3. Open Files 
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The character file above has two access paths, along each of which a 
program can read or write at the current byte, or character. The block file 
has two access paths, each of which can have a different current position, 
or mark, in the file. Each access path can move its own mark, and can 
read at the position it indicates. Both access paths share a common end- 
of-file marker, or EOF. 

In general, a block file can have either (a) one access path open for 
reading and writing or (b) one or more read-only access paths: it cannot 
have more than one access path if any access path can write to the file. A 
character file may have several access paths with write-access. 

SOS allows a maximum of 16 block-file access paths and 16 
character-file access paths to be open at one time. 

Each OPEN call to a file creates a new access path (with its own ref_num) 
to that file, which is separate from all the file's other access paths. 

When an access path to a file is closed, its FOB entry is deleted and its 
ref_num is released for use by other files. 

Certain operations, such as reading and writing, can only be performed on 
open files; others, such as renaming, can only be performed on closed 
files. 



4.1.3 Volumes 

A volume is a piece of random-access storage medium formatted to hold 
files. A volume is mounted on a block device, and is accessed through 
that device. Both flexible disks and hard disks are volumes. 

Each logical block device corresponds to one volume at any time. If the 
device uses removable media (like flexible disks), it can access different 
volumes at different times. 
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However, a single physical device can correspond to multiple logical 
devices, each with its own driver and device name. Each of these logical 
devices would have a volume with a different name. For example, if a disk 
drive contains a fixed disk and a removable disk, it would normally be 
treated as two logical devices, each with its own volume. It would have a 
driver module containing two drivers. The two logical devices would have 
different names and unit numbers; and the two volumes would have 
different names. 

It is even possible for a single medium to be divided into multiple volumes: 
a disk holding more than 64K blocks might be so divided, as SOS cannot 
support volumes larger than 64K blocks. In this case, the physical device 
is treated as multiple logical devices: the physical device has a single 
driver module, and each logical device has a uniquely named driver and 
volume. 

On the other hand, a driver for a disk drive containing several fixed disks 
might treat the disks as one large volume with one name. 

Having noted these special cases, we need not discuss them further. They 
are discussed in the Apple III SOS Device Driver Writer's Guide, as the 
relationships between logical devices and physical devices are 
established by device drivers. Since SOS and the interpreter deal only 
with volumes and logical devices, we can ignore physical devices without 
losing generality. From now on, the word device will mean logical device. 

Every volume must have two special items, each in a fixed place on the 
medium: a volume directory file and a bit map. The volume directory file 
contains information about the volume (such as its name and size), and 
information about files on the volume. The bit map represents every block 
on the volume with a bit indicating whether the block is currently allocated 
to a file, or is free for use. 

4.1.3. 1 Volume Switching 

Some devices (such as flexible-disk drives) have removable media. These 
devices can access several volumes, though only one at a time. This leads 
to problems, however, when a file has been opened on one volume in a 
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device, and subsequently that volume has been removed and another 
substituted for it. If SOS needs to access the open file on the original 
volume, it will not be able to find the volume it needs. 

When this happens, SOS will request that you restore the volume to its 
original drive. It halts all operations of the computer and displays a 
message on the screen (see Figure 4-4) 



Insert uolunie^ UTILITIES 

in del,' ice: qi 
then press the ALPHA LOCK key tuice 



Figure 4-4. The SOS Disk Request 



naming the volume it needs and the device into which it should be 
placed. The system will wait until you replace the volume and press the 
CAPS LOCK (on some keyboards called ALPHA LOCK) key on the 
keyboard twice. 

The volume-switching capability is very useful when you need to use 
many files on various volumes: it allows you to exchange volumes at 
will (when the device is idle), and still have all files accessible when they 
are needed. 



4. 1.3.2 Volume Names 

A block device is accessible by two names. The first is the device name, 
defined in Chapters. The second, more useful, name is the volume name. 
The volume name of a block device is the name of the volume currently in 
the device: the volume name of a flexible-disk drive will change as you 
insert and remove flexible disks. A block device containing no volume 
(such as an empty flexible disk drive) has no volume name and, to SOS, 
does not exist. 
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A volume name is up to 15 characters long: the first is a letter; the rest 
can be letters, digits, or periods, in any combination. A volume name is 
always preceded by a slash ( / ), but the slash is not part of the name. 
SOS automatically converts all lowercase letters in a volume name 
to uppercase. The syntax of a volume name is identical to that of a 
file name: a diagram is shown in section 4.2.2. 

Here are a few legal volume names, with slashes: 

/PROGRAMS 

/BLOCK.FILES 

/CHAP.2B 

Here are some volume names that will not work, and the reasons why: 

/BAD NAME (contains a space) 

/I .TO.10 (first character is a number) 

/STEVE'S.PROGRAM (contains an apostrophe) 

/ANTHROPOMORPHOUS (more than 1 5 characters) 

V\fe strongly recommend using the volume name, rather than the 
device name, whenever you refer to a block file. This has two 
advantages: 

• The user is protected against volume-swapping. 

• The program is more general: it can be used with new mass- 
storage devices without modification. 




4.2 The SOS File System 



SOS organizes all files it can access into a hierarchical tree structure, 
called the SOS file system. The top level of this system is shown in 
Figure 4-5. 
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Figure 4-5. Top-Level Files 

The top level contains character files and volume directories. Each 
character file represents one character device; each volume directory 
represents a volume on a block device, and can directly or indirectly 
access all files on the volume. Each character file is referred to by its 
device name; each volume directory is referred to by its volume 
(preferably) or device name. 

By comparing this diagram with that of the SOS device system, you can 
see that the file system is built on top of the device system: each file 
overlays a device. 



4.2. 1 Directory Files and Standard Files 

Since a volume on a block device can contain many files, SOS provides a 
special type of file, the directory file, to keep track of them. A directory is a 
file listing the names and locations of, as well as other information about, 
other files on the volume. The main directory on the volume is the volume 
directory, whose name is the same as its volume. The volume directory 
lists both standard files, which are block files containing data, and 
subdirectory files, which list other files. (A subdirectory file might not list 
any files: for example, if you have created a subdirectory file to list a 
series of future text files but have not yet created them.) If a directory lists 
a file, we may also say that it "owns" that file, or that is the "parent" of 
that file. 
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file 



Figure 4-6. The SOS File System 

We now have the whole tree: each node is a directory, and each leaf is a 
character or block file. We will give them names in a minute. 



4.2.2 File Names 

Each entry in a directory is listed by its file name, which distinguishes it 
from the other entries in that directory. For this reason, each file name in a 
directory must be unique. A file name is up to 15 characters long: the first 
is a letter; the rest are letters, digits, or periods, in any combination (see 
Figure 4-7). SOS automatically converts all lowercase letters in a file name 
to uppercase. 



I 

I 
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letter 









letter 



digit 



Figure 4-7. File Name Syntax 

Here are a few legal file names: 

MIKE.2.JULY.80 

SORTPROGRAM 

LETTER.TO.SUE 

Here are some file names that will not work, and the reasons why: 



BAD NAME 
1.TO.10 

STEVE'S.PROGRAM 
ANTHROPOMORPHOUS 



(contains a space) 
(begins with a number) 
(contains an apostrophe) 
(more than 15 characters) 



((^^) I n earlier editions of the Apple III Owner's Guide, file names are 
called local names. 



4.2.3 Pathnames 

A pathname is a sequence of names that defines a path from the root of 
the file system, through a volume directory and possibly subdirectories, 
to a specific file. 

A pathname uniquely identifies a file. Even if two files with the same 
file name appear in the system, they can be distinguished by their 
pathnames. 
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Figure 4-8. Pathname Syntax 



A pathname is composed of names and slashes (see Figure 4-8). A 
pathname begins with a slash and a volume name; a device name; or a 
file name; more file names may follow. One slash must separate any two 
successive names, and the last component of a pathname must be a 
name. As always, a volume name is preceded by a slash, and a device 
name begins with a period. 

Paths always begin at the root of the file system. The first component of 
the pathname determines the nature of the path. 



/vol_name If the first component is a slash followed by a volume name, 
the path proceeds from the volume directory. 

dev_name If the first component is the name of a block device (which 
begins with a period), SOS automatically replaces the 
device name with the name of the volume directory of the 
volume in that device, and the path proceeds from that 
directory. 

dev_name If the sole component is the name of a character device, 
the pathname specifies its character file. No further file 
specifications are allowed after a character device name. 

file_name If the first component is a file name, SOS appends the 

prefix (see below) to the pathname, and the new pathname 
is evaluated again. 



I 
I 
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Here is our file system tree again (see Figure 4-9), this time with the file 
names filled in: 











.CONSOLE 


















.GRAFIX 






Figure 4-9. Pathnames 
The valid pathnames in this file system are 



.CONSOLE /BASICSTUFF 
.GRAFIX /BASICSTUFF/SOS.DRIVER 
/PASCAL1 /BASICSTUFF/TEMPLATES 
/PASCAL1/S0S.DRIVER /BASICSTUFF/TEMPLATES/PHONES 
/PASCAL1/SYSTEM.PASCAL /BASICSTUFF/TEMPLATES/EXPENSES 

If the volume /PASCAL1 were installed in the device .D1 , then every 
pathname that included the volume /PASCAL1 would have a synonymous 
pathname using .D1 : for example, /PASCAL1/SOS.DRIVER would 
specify the same file as .D1/S0S.DRIVER . 



4.2.4 The Prefix and Partial Patlinames 

The prefix is a pathname that specifies a volume directory or subdirectory 
file. When SOS boots, the prefix is set to the volume directory of the boot 
volume. 
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A partial pathname is a pathname that begins with a file name, whereas a 
full pathname begins with a volume or device name. In other words, a 
partial pathname begins with a letter, whereas a full pathname begins with 
a slash or period. When SOS receives a partial pathname, it concatenates 
the prefix to that pathname with a slash, forming a full pathname. The 
effect is to allow you to specify a "current directory", or prefix, and refer to 
files owned by that directory without having to specify the directory's 
pathname each time. For example, the prefix /PASCAL1 and the partial 
pathname SOS.DRIVER form the full pathname /PASCAL1/S0S.DRIVER. 

The prefix always specifies a volume directory or subdirectory file. The 
prefix never specifies a standard or character file. 

The SOS prefix is not the Pascal prefix. The two may or may not 
have the same value. 

4.3 File and Access Path Information 



An interpreter often needs information about a file or an access path. 
Information about a block file is stored in the file's directory entry. 
Information about a block file access path is stored in its FOB entry. This 
section describes file information and access path information for block 
files only. Information about a character file is stored as the device 
information of its respective character device (see section 3.3). No 
corresponding information about an access path to a character file is 
available through SOS. 

The various items of information about a file will be named in boldface, 
and the same names will be used when these items appear as fields in 
directories (in Chapter 5) and as parameters for SOS calls (in Chapter 8 
and in Volume 2). 

4.3.7 File Information 

Certain information about a block file, such as a file's name, belongs to the 
file itself rather than to any of its access paths. This information is stored 
in that file's directory entry (see section 5.2.4). 
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An interpreter can read the file information in the directory entry with a 
GET_FILE_INFO call or change it with a SET_FILE_INFO call, both 
described in Chapter 10 of Volume 2. No change, however, can be made 
to any of the file information if the file is open: a SET_FILE_INFO call to 
do so will have no effect until the file is closed. 

This information about a file is kept in the directory entry: 

filename 

A closed block file is accessed by its file_name. The file name of a block 
file can be changed, but only when the file is closed. Only the last file 
name in a pathname can be changed, because the preceding names are 
the names of open directory files, which are shared with other files. 

All access to information about a closed block file is through its 
file name. 



access 

Every block file has an access attribute field, which determines the ways in 
which you may use that file. The access attributes can be set to prevent 
you from reading from, writing to, renaming, or destroying a file. It can 
also tell you whether a file's contents have been changed since the last 
time a backup copy of the file was made. 

EOF and biocks_used 

The number of bytes in a block file is specified by the end-of-file pointer, 
or EOF. The number of blocks physically used by the file is specified by 
the blocks_ used item. In sparse files, which we will see later, the EOF and 
blocks_used numbers may not correspond as you might expect. 

GET_FILE_INFO returns the current value of EOF and 
blocks used only if the file is closed. If it is open, GET_EOF 
returns'the correct value of EOF. GET_FILE_INFO returns the 
values EOF and blocks used had when the file was opened. 
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storagetype, filetype, and auxtype 

Three items describe the external and internal arrangement of each block 
file. The storage_type indicates whether the file is a directory file or a 
standard file, and how the file is stored on its block device: this item is 
used only by SOS. The file_type classifies the contents of the file; and the 
aux_type can be used by an interpreter as an additional description of the 
contents of the file: these two items are used only by the interpreter. 

A description of the identification codes and their meanings is given later 
in this chapter 

creation and last mod 

These items record the dates and times at which a block file was initially 
created and last updated. These values are drawn from the system clock 
or the last known time. 

4.3.2 Access Path Information 

Other information about a block file, such as an interpreter's position in a 
file, belongs to the access path rather than the file itself. This information 
is stored in the access path's entry in the File Control Block. 

Access path information can be changed only while that access path is 
open. When the access path is closed, certain items, such as the mark, 
disappear, and others, such as the EOF, update the file information in the 
directory entry. 

This information about the access path is kept in the FOB entry: 
refnum 

When an access path to a file is opened, SOS assigns that access path a 
unique reference number, or ref_num. All subsequent references to that 
access path must be made with that ref_num. 

EOF and mark 

Each access path to an open block file has one attribute defining the end 
of file, the EOF, and another defining the current position in the file, the 
mark. Both of these may be moved automatically by SOS or manually by 
the interpreter. 
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The EOF pointer is the number of bytes in the file. This is equivalent to 
pointing one position beyond the last byte in the file, since the first byte is 
byte number 0: in an empty file (containing zero bytes), EOF points at byte 
number 0. The value of the mark cannot exceed the value of EOF. 



The EOF is peculiar in that it appears both in the file's directory entry and 
in the access path's FOB entry. When a file is open for writing, the two 
values of the EOF may differ The current EOF is stored in the access 
path's FOB entry: this EOF is returned by a GET_EOF call to the ref_num. 
The value of EOF in the file's directory entry is updated only when the 
access path is closed: this EOF is returned by a GET_FILE_INFO call to 
the file name. 

It is impossible for two access paths to have different EOF values, for in 
order to change the EOF, an access path must have write-access. If it 
does have write-access, it must be the only access path to that file. 

The mark automatically moves forward one byte for every byte read from 
or written to the file. Thus, the mark always indicates where the next byte 
will be read or written. 



If, during a WRITE operation, the mark meets the EOF, both the mark and 
the EOF are moved forward one position for every additional byte written 
to the file. Thus, adding bytes to the end of the file automatically moves 
the EOF up to accommodate the new information. Figure 4-10 shows the 
automatic movement of EOF and mark. 



EOF 



EOF 
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after writing 2 bytes 



Figure 4-10. Automatic Movement of EOF and Mark 



An interpreter can manually move the EOF to place it anywhere from the 
current mark position to the maximum byte position possible (see Figure 
4-11). The mark can also be placed anywhere from the first byte in the file 
to the current position of the EOF. 
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Figure 4-1 1 . Manual Movement of EOF and Mark 

The EOF is read by the GET_EOF call and manually set by the 
SET_EOF call; the mark is read by the GET_MARK call and manually 
set by the SET_MARK call. 

level 

Each access path is given a level when it is opened. The level of the 
access path is the value of the system file level at the time the access path 
was opened. An interpreter can group files by file levels (for example, have 
user files open at one level, while system files are open at another), and 
perform group operations on files of like levels. 

The system file level has the value 1 , 2, or 3. When the system is booted, 
the level is set to 1 . It can be changed by the SET_LEVEL call, and read 
by the GET_LEVEL call. One use of the file level is to close all files 
opened by a user program when the interpreter exits that program. 

This is done as follows: When the interpreter enters the program, it 
raises the system file level. Thus all files opened by the program will have 
a higher level than, say, .CONSOLE or the interpreter file. When the 
interpreter exits the program, it issues a FLUSH call or CLOSE call with a 
ref_num of $00, which closes all files at a level equal to or higher than the 
system file level. Then the interpreter lowers the system file level. 



mark 
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4.3.3 Newline Mode Information 

Certain information about a file, called newline-mode information, is 
associated either with the file itself or with an access path to the file, 
depending on the kind of file. A character file's newline-mode information 
is associated with the file and its device; a block file's newline-mode 
information is associated with an access path to the file, and can differ 
from one access path to another 

When SOS reads from an open file, it can read input as a continuous 
stream of characters or as a series of lines. In the first case, you ask SOS 
to read a specific number of bytes: when this number have been read or 
when the current position has reached the end of file, the READ operation 
terminates. In the second case, called newline mode, the READ will also 
terminate if a specified character, the newline character, is read. The 
newline character is usually the ASCI I OR ($0D), but can be any hex value 
from $00 to $FF The newline character is called the termination character 
or line-termination character in the Apple III Standard Device Drivers 
Manual. 

Newline mode is supported on both character and block files, so that file 
input/output can be device independent. For example, a program that 
reads a line of text from a file can treat the keyboard and a disk file exactly 
the same way. 

is newline and newline char 

Newline mode is controlled by two values: is_newline turns newline mode 
on or off; newline_char sets the newline character These two values are 
set by the NEWLINE call to the access path's ref_num. 

For a block file, each access path can have separate Is.newllne 
and new1ine_char values. A character file also has ls_newline and 
newilne.char values, which are also changed by a NEWLINE call 
to an access path's ref_num, but they are the same for all access 
paths. If either value is changed for one access path, it is 
changed for all. 
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4.4 Operations on Files 

These operations can be performed on all files: 

• OPEN and CLOSE to control access, and READ and WRITE (if its 
access attributes allow) to transfer information from or to the file. 

• Change is newline and newline char for an access path, using the 
NEWLINE~call. 

These operations can be performed only on block files: 

• Examine or change file information, including the name, access, 
file type, and modification date, using the GET_FILE_INFO and 
SET_FILE_INFO calls. 

These operations can be performed only on closed block files: 

• CREATE a new file; 

• DESTROY an existing file; 

These operations can be performed only on standard files open for 
writing: 

• Set and read the EOF pointer, using the SET_EOF and 
GET_EOF calls. 

• Set and read the current position mark, using the SET_MARK 
and GET_MARK calls. 

These operations can be performed on directory files: 

• OPEN and CLOSE the file. 

• READ the file, if it is open. 

• DESTROY the file, if it is empty and closed. 
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4.5 FiieCails 



These calls deal with files: the calls CREATE through OPEN operate on 
closed files; the calls NEWLINE through GET_LEVEL operate on open 
files. The name of each call below is followed by its parameters (in 
boldface). The input parameters are directly-passed values and pointers 
to tables. The output parameters are all directly-passed results. The first 
list is of required parameters; the second list, present for some calls, is of 
optional parameters. The SOS call mechanism is explained in Chapter 8; 
the individual calls are described fully in Volume 2, Chapter 9. 

CREATE 

[pathname, optionjist: pointer; length: value] 

[file type, aux type, storage type, EOF: optional value] 

This call creates a standard file or subdirectory file on a block device. 
A file entry is placed in a directory, and at least one block is allocated. 

DESTROY 
[pathname: pointer] 

This call deletes the file specified by the pathname parameter by marking 
the file's directory entry inactive. DESTROY releases all blocks used by 
that file back to free space on that volume. 

The file can be either a standard or a subdirectory file. A volume directory 
cannot be destroyed except by physically reformatting the medium. A 
character file can be removed from the system by the System 
Configuration Program. 

RENAME 

[pathname, new_pathname: pointer] 

This call changes the name of the file specified by the pathname 
parameter to that specified by new_pathname. Only block files may be 
renamed; character files are "renamed" by the System Configuration 
Program. 
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SET_FILE_INFO 

[pathname, optionjist: pointer; length: value] 

[access, file type, aux type, last mod: optional value] 

This call modifies information in the directory entry of the file specified by 
the pathname parameter. Only block files' information can be modified; 
character files have no such information associated with them. 

You may perform a SET_FILE_INFO on a currently-open file, but the 
new information will not take effect until the next time the file is OPENed. 

GET_FILE_INFO 

[pathname, optionjist: pointer; length: value] 

[access, file_type, aux_type, storage type, EOF, blocks, 
last_mod: optional result] 

This call returns information about the block file specified by the 
pathname parameter. 

VOLUME 

[dev name, vol name: pointer; blocks, free blocks: result] 

When given the name of a device, this call returns the volume name of the 
volume contained in that device, the number of blocks on that volume, 
and the number of currently unallocated blocks on that volume. 

SET_PREFIX 
[pathname: pointer] 

This call sets the operating-system pathname prefix to that specified in 
pathname. 

GET_PREFIX 

[pathname: pointer; length: value] 

This call returns the current system pathname prefix. 
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OPEN 

[pathname: pointer; ref num: result; optlon_list: pointer; length: value] 
[req_access, pages: optional value; io_buffer: optional pointer] 

This call opens an access path to the file specified by pathname for 
reading or writing or both. SOS creates an entry in the file control block 
and an I/O buffer. 

NEWLINE 

[ref_num, is newllne, newline_char: value] 

This call allows the caller to selectively enable or disable "newline" read 
mode. Once newline mode has been enabled, any subsequent read 
request will immediately terminate if the newline character is encountered 
in the input byte stream. 

READ 

[ref num: value; data buffer: pointer; request_count, 
transfer_count: value] 

This call attempts to transfer request_count bytes, starting from the 
current position (mark), from the file specified by ref_num into the buffer 
pointed to by data_buffer. If newline read mode is enabled and the 
newline character is encountered before request_count bytes have been 
read, then the transfer_count parameter will be less than request_count 
and exactly equal to the number of bytes transferred, including the 
newline byte. 

WRITE 

[ref num: value; data_buffer: pointer; request count: value] 

This call transfers request_count bytes, starting from the current file 
position (mark), from the buffer pointed to by data_buffer to the open file 
specified by ref_num. 



72 SOS Reference Manual 



CLOSE 

[ref_num: value] 

This call closes the file access path specified by ref_num. Its file-control 
block is released, and if the file is a block file that has been written to, its 
write buffer is emptied. The directory entry for the file, if any, is updated. 
Further file operations using that ref_num will fail. If ref_num is $00, all files 
at or above the system file level are closed. 

FLUSH 

[ref_num: value] 

This call flushes the file access path specified by ref_num. If the file is a 
block file that has been written to, its I/O buffer is emptied. The access 
path remains open. If ref_num is $00, all files at or above the system file 
level are flushed. 

SET_MARK 

[ref num, base, displacement: value] 

This call changes the current file position (mark) of the file access path 
specified by ref_num. The mark can be changed to a position relative to 
the beginning of the file, the end of the file, or the current mark. 

GET_MARK 

[ref_num: value; mark: result] 

This call returns the current file position (mark) of the file access path 
specified by ref_num. 

SET_EOF 

[ref num, base, displacement: value] 

This call moves the end-of-f ile marker (EOF) of the specified block file to 
the indicated position. The EOF can be changed to a position relative to 
the beginning of the file, the end of the file, or the current mark. 
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If the new EOF is less than the current EOF, then empty blocks at the end 
of the file are released to the system and their data are lost. The converse 
is not true: if the new EOF is greater than the current EOF, then blocks 
are not allocated, creating a sparse file; reading from these newly created 
positions before they are written to results in $00 bytes. 

GET_EOF 

[ref_num: value; EOF: result] 

This call returns the current end-of-file (EOF) position of the file specified 
by ref num. 

SET_LEVEL 
[level: value] 

This call changes the current value of the system file level. All subsequent 
OPENS will assign this level to the files opened. All subsequent CLOSE 
and FLUSH operations on multiple files (using a ref_num of $00) will 
operate on only those files that were opened with a level greater than or 
equal to the new level. 

GET_LEVEL 
[level: result] 

This call returns the current value of the system file level. See 
SET_LEVEL, OPEN, CLOSE, and FLUSH. 
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When a program accesses a block device, it actually accesses the volume 
that corresponds to that device. You have already learned of the 
hierarchical tree structure used by SOS in its file organization, of the 
naming conventions used to access any file within the tree structure, and 
of the logical structure of a file as a sequence of bytes; this chapter 
explains the physical implementation of these structures on any volume. 

The first part of the chapter (section 5.1 ) discusses what is on a volume, 
the second (section 5.2) describes directory files, the third part of the 
chapter (section 5.3) discusses standard files, and the final part of the 
chapter (section 5.4) provides a graphic summary of the organization of 
information on volumes. 

The focus of this chapter is on how SOS works, not on how to use it. For 
this reason, we have chosen to explain details of implemention that are 
not strictly necessary for an interpreter writer to know, in order to make 
the working of SOS more concrete. The only section that is of immediate 
practical use to an interpreter writer is section 5.2 on the formats of 
directory files. The rest of the chapter explains the implementation of the 
file system: these sections should be regarded as examples, not as 
specifications. 

In this manual, we will distinguish the SOS interface, which is supported, 
and the SOS implementation, which is not. We will support the 
hierarchical tree structure of the file system and the logical structures of 
character and block files. We will also support the storage formats of 
directory headers and entries, although they may be expanded by 
appending new fields. However, we may change volume formats and the 
storage formats of standard files. 

Programmers should not rely on the details of implementation, as 
we may change the storage formats of files in order to improve 
performance. An interpreter that uses the READ and WR ITE calls 
to access files, and interprets directories as we explain here, will 
work with future versions of SOS. An interpreter that relies on the 
current disk-allocation scheme or index-block structure may not 
work with future versions. 
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5. 1 Format of Information on 
a Volume (SOS 1.2) 



This section explains how SOS 1 .2 organizes information on a 280-block 
flexible disk: it should be regarded as an example, not a general 
specification for volume formats. 

In accessing a volume, SOS requests a logical block from the device 
corresponding to that volume. Logical blocks may be supported physically 
by tracks and sectors, or cylinders and heads, or other divisions. This 
translation is done by the device driver: the physical location of 
information on a volume is unimportant to SOS. This chapter discusses 
the organization of information on a volume in terms of blocks, numbered 
starting with 0. 

When the volume is formatted, information needed by SOS is placed in 
specific logical blocks. A bootstrap loader program is placed in blocks 
and 1 of the volume. This program loads SOS from the volume when 
CONTROL-RESET is pressed. Block 2 of the volume is the first block, or 
key block, of the volume directory file: it contains descriptions and 
locations of all the files in the volume directory, as well as the location of 
the volume bit map. The volume directory occupies a number of 
consecutive blocks (4 for SOS 1.2), and normally is immediately followed 
by the volume bit map, which records whether each block on the volume 
is used or unused. The volume bit map occupies consecutive blocks, one 
for every 4,096 blocks (or fraction thereof) on the volume. The rest of the 
blocks on the disk contain either subdirectory file information, standard 
file information, or garbage (such as parts of deleted files). The first 
blocks of a volume look something like this (Figure 5-1 ): 
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Figure 5-1. Blocks on a Volume 

The precise format of the volume directory, volume bit map, subdirectory 
files and standard files are explained in the following sections. 
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5.2 Format of Directory Files 



The format of the information contained in volume directory and 
subdirectory files is quite similar Each directory file is a linked list of one 
or more blocks: each block contains pointers to the preceding and 
following blocks, a series of entries, and unused bytes at the end. The first 
block, called the key block, has no preceding block, so its preceding-block 
pointer is zero; the last block has no following block, so its following-block 
pointer is zero. 

Most entries in a directory describe other files, which can be either 
standard files or directories: these entries are called file entries. The first 
entry in the key block of a directory contains information about the 
directory itself, not about another file: this entry is called the directory 
header. 



The format of a directory file is represented in Figure 5-2. 
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Figure 5-2. Directory File Format 
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The header entry is the same length as all other entries. As will be 
described below, the only organizational difference between a volume 
directory file and a subdirectory file is in the header. 

5.2.7 Pointer Fields 

The first four bytes of each block used by a directory file contain pointers 
to the preceding and succeeding blocks, respectively, of the directory file. 
Each pointer is a two-byte logical block number, low byte first, high byte 
second. The key block of a directory file has no preceding block: its first 
pointer is zero. Likewise, the last block in a directory file has no successor: 
its second pointer is zero. If a directory occupies only one block, both 
pointers are zero. 

A pointer of value zero causes no ambiguity: no directory block 
could occupy block 0, as blocks and 1 are reserved for the 
bootstrap loader 

All block pointers used by SOS have the same format: low byte first, high 
byte second. 

5.2.2 Volume Directory Headers 

Block 2 of a volume is the key block of that volume's directory file. One 
finds the volume directory header at byte position 0004 of the key block, 
immediately following the block's two pointers. 

Figure 5-3 illustrates the structure of a volume directory header: following 
the figure is a description of each field. If you compare Figure 5-3 with 
Figure 5-4, you will notice that the two header types have the same 
structure for the first 12 fields, from storage_type to file_count; after that, 
the two diverge. However, similarly named fields have different meanings 
for the two types, so we have described each type separately. 
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Figure 5-3. The Volume Directory Header 
storage type and name_length (1 byte): 

Two four-bit fields are packed into this byte. A value of $F in the high four 
bits (the storage_type) identifies the current block as the key block of a 
volume directory file. The low four bits contain the length of the volume's 
name (see the file name field, below). The name iength can be changed 
byaRENAMEcalL 

file_name (15 bytes): 

The first name_iength bytes of this field contain the volume's name. This 
name must conform to the file name (or volume name) syntax explained 
in Chapter 4. The name does not begin with the slash that usually 
precedes volume names. This field can be changed by the RENAME call. 
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reserved (8 bytes): 

This field is reserved for future expansion of the file system, 
creation (4 bytes): 

This field holds the date and time at which this volume was initialized. The 
format of these bytes is described in section 5.4.2.2. 

version (1 byte): 

This is the version number of SOS under which this volume was initialized. 
This byte allows newer versions of SOS to determine the format of the 
volume, and adjust their directory interpretation to conform to older 
volume formats. 

ForSOS 1.2, version = 0. 

min version (1 byte): 

This is the minimum version number of SOS that can access the 
information on this volume. This byte allows older versions of SOS to 
determine whether they can access newer volumes. 

For SOS 1 .2, min version = 0. 

access (1 byte): 

This field determines whether this volume directory may be read, written, 
destroyed, and renamed. The format of this field is described in section 
5.4.2.3. 

entry length (1 byte): 

This is the length in bytes of each entry in this directory. The volume 
directory header itself is of this length. 

For SOS 1 .2, entiy_length = $27. 



82 SOS Reference Manual 



entriesperblock (1 byte): 

This is the number of entries that are stored in each blocl< of the 
directory file. 

For SOS 1 .2, entries_per_block = $0D. 
file_count (2 bytes): 

This is the number of active file entries in this directory file. An active file 
is one whose storage_type and name_length are not 0. See section 5.2.4 
for a description of file entries. 

bit_map_pointer (2 bytes): 

This is the block address of the first block of the volume's bit map. The bit 
map occupies consecutive blocks, one for every 4,096 blocks (or fraction 
thereof) on the volume. You can calculate the number of blocks in the bit 
map from the total_blocks value, described below. 

The bit map has one bit for each block on the volume: a value of 1 means 
the block is free; means it is in use. 

total blocks (2 bytes): 

This is the total number of blocks on the volume. 

5.2.3 Subdirectory Headers 

The key block of every subdirectory file is pointed to by an entry in 
another directory (explained below). A subdirectory header begins at 
byte position $0004 of the key block of that subdirectory file, immediately 
following the two pointers. Its internal structure is quite similar to that of a 
volume directory header. Figure 5-4 illustrates the structure of a 
subdirectory header A description of all the fields in a subdirectory 
header follows the figure. 



I 

I 
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Figure 5-4. The Subdirectory Header 



storage type and name length (1 byte): 

Two four-bit fields are packed into this byte. A value of $E in the high four 
bits (the storage_type) identifies the current block as the key block of a 
subdirectory f ile~The low four bits contain the length of the subdirectory's 
name (see the file name field, below). The name_length can be changed 
by a RENAME calL 

file_name (15 bytes): 

The first name-length bytes of this field contain the subdirectory's name. 
This name must conform to the file name syntax explained in Chapter 4. 
This field can be changed by the RENAME call. 
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reserved (8 bytes): 

This field is reserved for future expansion of the file system, 
creation (4 bytes): 

This is the date and time at which this subdirectory was created. The 
format of these bytes is described in section 5.4.2.2. 

version (1 byte): 

This is the version number of SOS under which this subdirectory was 
created. This byte allows newer versions of SOS to determine the format 
of the subdirectory, and to adjust their directory interpretations 
accordingly. 

ForSOS 1.2, version = 0. 



min version (1 byte): 

This is the minimum version number of SOS that can access the 
information in this subdirectory. This byte allows older versions of SOS to 
determine whether they can access newer subdirectories. 

For SOS 1 .2, min version = 0. 



access (1 byte): 

This field determines whether this subdirectory may be read, written, 
destroyed, and renamed. The format of this field is described in section 
5.4.2.3. A subdirectory's access byte can be changed by the 
SET_FILE_INFO call. 

entry_length (1 byte): 

This is the length in bytes of each entry in this subdirectory. The 
subdirectory header itself is of this length. 

For SOS 1 .2, entryjength = $27. 
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entries_per_biock (1 byte): 

This is the number of entries that are stored in each block of the directory 
file. 

For SOS 1 .2, entries_per_biock = $0D. 
filecount (2 bytes): 

This is the number of active file entries in this subdirectory file. An active 
file is one whose storagejype and name_length are not 0. See the next 
section for more information about file entries. 

parent pointer (2 bytes): 

This is the block address of the directory file block that contains the entry 
for this subdirectory. This two byte pointer is stored low byte first, high 
byte second. 

parent_entry_ number (1 byte): 

This is the entry number for this subdirectory within the block indicated 
by parent_pointer. 

parent entryjength (1 byte): 

This is the entry_ length for the directory that owns this subdirectory file. 
Note that with these last three fields one can calculate the precise position 
on a volume of this subdirectory's file entry. 

For SOS 1 .2, parent entry jength =$27. 

5.2.4 File Entries 

Immediately following the pointers in any block of a directory file are a 
number of entries. The first entry in the key block of a directory file is a 
header; all other entries are file entries. Each entry has the length specified 
by that directory's entry_length field, and each file entry contains 
information that describes, and points to, a single subdirectory file or 
standard file. 
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An entry in a directory file may be active or inactive; that is, it may or may 
not describe a file currently in the directory. If it is inactive, the 
storage type and name_length fields are zero. 

The maximum number of entries, including the header, in a block of a 
directory is recorded in the entries_per_block field of that directory's 
header The total number of active file entries, not including the header, is 
recorded in the file_count field of that directory's header 

Figure 5-5 describes the format of a file entry. 
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Figure 5-5. The File Entry 
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storagejype and name length (1 byte): 

Two four-bit fields are packed into this byte. The value in the high-order 
four bits (the storage_type) specifies the type of file this entry points to. 
The values $1 , $2, $3, and $D denote seedling, sapling, tree, and 
subdirectory files, respectively. Seedling, sapling, and tree files, the three 
forms of a standard file, are described later in this chapter. The low-order 
four bits contain the length of the file's name (see the file_name field, 
below). If a file entry is inactive, the storagejype and name_length are 
zero. The name_length can be changed by a RENAME call. 

file name (15 bytes): 

The first name_length bytes of this field contain the file's name. This 
name must conform to the file name syntax explained in Chapter 4. This 
field can be changed by the RENAME call. 

file_type (1 byte): 

This specifies the internal structure of the file. Section 5.4.2.3 contains a 
list of the currently defined values of this byte. 

l(ey_pointer (2 bytes): 

This is the block address of the key block of the subdirectory or standard 
file described by this file entry. 

blocl(S_used (2 bytes): 

This is the total number of blocks actually used by the file. For a 
subdirectory file, this includes the blocks containing subdirectory 
information, but not the blocks in the files pointed to. For a standard file, 
this includes both informational blocks (index blocks) and data blocks. 
Refer to section 5.3 for more information on standard files. 

EOF (3 bytes): 

This is a three-byte integer, lowest bytes first, that represents the total 
number of bytes readable from the file. Note that in the case of sparse 
files, described later in the chapter, EOF may be greater than the number 
of bytes actually allocated on the disk. 
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creation (4 bytes): 

This is tine date and time at which the file pointed to by this entry was 
created. The format of these bytes is described in section 5.4.2.2. 

version (1 byte): 

This is the version number of SOS under which the file pointed to by this 
entry was created. This byte allows newer versions of SOS to determine 
the format of the file, and adjust their interpretation processes accordingly. 

For SOS 1.2, version = 0. 

min version (1 byte): 

This is the minimum version number of SOS that can access the 
information in this file. This byte allows older versions of SOS to determine 
whether they can access newer files. 

For SOS 1 .2, min version = 0. 

access (1 byte): 

This field determines whether this file can be read, written, destroyed, 
and renamed. The format of this field is described in section 5.4.2.3. The 
value of this field can be changed by the SET_FILE_INFO call. 

aux_type (2 bytes): 

This is a general-purpose field in which an interpreter can store additional 
information about the internal format of a file. For example, BASIC uses 
this field to store the record length of its data files. This field can be 
changed by the SET_FILE_INFO call. 

last_mod (4 bytes): 

This is the date and time that the last CLOSE operation after a WRITE 
was performed on this file. The format of these bytes is described in 
section 5.4.2.2. This field can be changed by the SET_FILE_INFO call. 
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headerpointer (2 bytes): 

This field is the block address of the key block of the directory that owns 
this file entry. This two byte pointer is stored low byte first, high byte 
second. 



5.2.5 Field Formats in Detail 

Several of the fields above occur in more than one kind of directory entry. 
Therefore, we have pulled them out for more detailed explanation here. 

5.2.5. 1 The storagejype Field 

The storage_type, the high-order four bits of the first byte of an entry, 
defines the type of header (if the entry is a header) or the type of file 
described by the entry. 

$0 indicates an inactive file entry 
$1 indicates a seedling file entry 

( 0<-EOF<=512bytes) 
$2 indicates a sapling file entry 

(512<EOF<=128K bytes) 
$3 indicates a tree file entry 

(128K<EOF<16M bytes) 
$D indicates a subdirectory file entry 
$E indicates a subdirectory header 
$F indicates a volume directory header 

SOS automatically changes a seedling file to a sapling file and a sapling 
file to a tree file when the file's EOF grows into the range for a larger type. 
If a file's EOF shrinks into the range for a smaller type, SOS changes a 
tree file to a sapling file and a sapling file to a seedling file. 

5.2.5.2 The creation and lastjnod Fields 

The date and time of the creation, and of the last modification, of each file 
and directory are stored as two four-byte values (see Figure 5-6): 
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Figure 5-6. Date and Time Format 

The values for the year, month, day, hour, and minute are stored as 
unsigned binary integers, and may be unpacked for analysis. Note that 
the SOS calls GET_TIME and SET_TIME represent dates and times 
differently. 

5.2.5.3 The access A ttributes 

The access attribute field determines whether the file can be read from, 
written to, deleted, or renamed. It also tells whether a backup copy of the 
file has been made since the file's last modification (see Figure 5-7). 
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Figure 5-7. The access Attribute Field 

A bit set to 1 indicates that the operation is enabled; a bit cleared to 
indicates that the operation is disabled. The reserved bits are always 0. 

SOS sets bit 5 (the backup bit) of the access field to 1 whenever the file is 
changed (that is, after a CREATE, RENAME, CLOSE after WRITE, or 
SET_FILE_INFO operation). This bit is cleared to whenever the file is 
copied by Backup III. This lets Backup III selectively back up files that 
have been changed since the last backup was made. 



■ 
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Only SOS may change bits 2-4. Only SOS and Backup III may 
change bit 5. 

5.2.5.4 The file Jype Field 

The file_type field within an entry identifies the type of file described by 
that entry. This field should be used by interpreters to guarantee file 
compatibility from one interpreter to the next. The values of this byte are 
defined below: 



$00 = Typeless file (BASIC "unknown" file) 

$01 - File containing all bad blocks on the volume 

$02 = Pascal or assembly-language code file 

$03 = Pascal text file 

$04 = BASIC text file; Pascal ASCII file 

$05 = Pascal data file 

$06 = General binary file 

$07 = Font file 

$08 = Screen image file 

$09 = Business BASIC program file 

$0A = Business BASIC data file 

$0B = Word Processor file 

$0C = SOS system file (DRIVER, INTERP KERNEL) 

$0D,$0E = SOS reserved 

$0F = Directory file (see storage_type) 

$10-$BF = SOS reserved 

$C0-$FF= ProDOS reserved 



5. 2. 6 Reading a Directory File 

Reading a directory file is straightforward, but your program must be 
written to allow for possible changes in the entry length and the number of 
entries per block: future versions of SOS may change these by adding 
more information at the end of an entry. Since these values are in the 
directory header, this flexibility is not difficult to achieve. 
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The first step in reading a directory file is to open an access path to the 
file, and obtain a ref_num. Using the ref_num to identify the file, read the 
first 512 bytes of the file into a buffer The buffer contains two two-byte 
pointers, followed by the entries: the first entry is the directory header. 
Bytes $1 F through $20 in the header (bytes $23 through $24 in the buffer) 
contain the values of entry_length and entries_per_block. 

Once these values are known, an interpreter can read through the entries 
in the buffer, using a pointer to the beginning of the current entry and a 
counter indicating the number of entries examined in the current block. 
Any entry whose first byte is zero is ignored. When the counter equals 
entries_per_block, read the next 512 bytes of the file into the buffer. When 
a READ returns a bytes_read parameter of zero, you have processed the 
entire directory file. 

5.3 Storage Formats of Standard Files 



Each active entry in a directory file points (using its key_pointer field) to 
the key block of another directory file or to the key block of a standard file. 
An entry that points to a standard file contains information about the file: 
its name, its size, its type, and so on. 

Depending on its size, a standard file can be stored in any of the three 
formats explained below: seedling, sapling, and tree. An interpreter can 
distinguish between these three (using the file entry's storagejype field), 
but it need not, for an interpreter reads every standard file in exactly the 
same way, as a numbered sequence of bytes. Only SOS needs to know 
how a file is stored. Nevertheless, we think it is useful for programmers to 
understand how SOS stores data on a volume. 

The storage formats in this section apply to SOS 1 .2. They may 
change in future versions of SOS. 

5.3. 1 Growing a Tree File 

As a tree file grows, it goes through three storage formats, as explained in 
the following scenario. In the scenario, we start with an empty, formatted 
volume, create one file, then increase its size in stages. 
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This scenario is based on the block-allocation scheme used by 
SOS 1 .2 on a 280-block flexible disk, which contains four blocks 
of volume directory, and one block of volume bit map. This 
scheme is subject to change in future versions of SOS. 

Larger capacity volumes might have more blocks in the volume bit map, 
but the process would be the same. 

A formatted, but otherwise empty 280-block SOS disk is used like this: 

Blocks 0-1 Bootstrap Loader 

Blocks 2-5 : Volume Directory 

Block 6 : Volume Bit Map 

Blocks 7-279 : Unused 



If you open a new standard file, one data block is immediately allocated 
to that file. An entry is placed in the volume directory, and it points to 
block 7, the new data block, as the key block for the file. The volume now 
looks like this: 



Blocks 0-1 Bootstrap Loader 

Blocks 2-5 Volume Directory 

Block 6 : Volume Bit Map 

~* Block 7 : Data Block 

Blocks 8-279 : Unused 

This is a seedling file: its key block contains up to 512 bytes of data. If you 
write more than 512 bytes of data to the file, the file grows into a sapling 
file. As soon as a second block of data becomes necessary, an index 
block is allocated, and it becomes the file's key block: this index block 
can point to up to 256 data blocks (two-byte pointers). A second data 
block (for the data that won't fit in the first data block) is also allocated. 
The volume now looks like this: 



Key Block Pointer 



data 
block 
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Blocks 0-1 
Blocks 2-5 
Block 6 
Block 7 
Block 8 
Block 9 
Blocks 10-279 



Bootstrap Loader 
Volume Directory 
Volume Bit Map 
Data Block 
Index Block 
Data Block 1 
Unused 



Key Block Pointer 



index 
block 



data 




data 


block 




block 1 



This sapling file can hold up to 256 data blocks: 1 28K of data. If the file 
becomes any bigger than this, the file grows again, this time into a free 
file. A master index block is-allocated, and it becomes the file's key block: 
the master index block can point to up to 128 index blocks, and each of 
these can point to up to 256 data blocks. Index block becomes the first 
subindex block, which is an index block pointed to by the master index 
block. In addition, a new subindex block is allocated, and a new data 
block to which it points. Here's a new picture of the volume: 



Blocks 0-1 
Blocks 2-5 
Block 6 
Block 7 
Block 8 
Blocks 9-263 
Block 264 
Block 265 
Block 266 
Blocks 267-279 



Bootstrap Loader 
Volume Directory 
Volume Bit Map 
Data Block 
Index Block 
Data Blocks 1-255 
Master Index Block 
Index Block 1 ^ 
Data Block 256 
Unused 



Key Block Pointer 



master 
index 
block 



index 




index 


block 




block 1 



/ 



data 




data 




data 


block 




block 255 




block 256 



As data are written to this file, additional data blocks and index blocks are 
allocated as needed, up to a maximum of 129 index blocks (one master 
index block and 128 subindex blocks), and 32,768 data blocks, for a 
maximum capacity of 16,777,215 bytes of data in a file. If you did the 
multiplication, you probably noticed that we lost a byte somewhere. The 
last byte of the last block of the largest possible file cannot be used 
because EOF cannot exceed 16,777,215. If you are wondering how such a 
large file might fit on a small volume such as a floppy disk, refer to the 
section on sparse files, later in this chapter. 



I 
I 
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This scenario shows the growth of a single file on an otherwise empty 
volume. The process is a bit more confusing when several files are 
growing (or being deleted) simultaneously. However, the block allocation 
scheme is always the same: when a new block is needed, SOS always 
allocates the first unused block in the volume bit map. 



5.3.2 Seedling Files 

A seedling file is a standard file that contains no more than 51 2 data bytes 
($0 <= EOF <= $200). This file is stored as one block on the volume, and 
this data block is the file's key block. 

One block is always allocated for a seedling file, even if no data 
have been written to the file. 



The structure of such a seedling file looks like this (Figure 5-8): 



key_ pointer 





data 


$200 


block 



Data Block 
512 bytes long. 



Figure 5-8. Structure of a Seedling File 



The file is called a seedling file because, if more than 512 data bytes are 
written to it, it grows into a sapling file, and thence into a tree file. 



The storage_type field of an entry that points to a seedling file has the 
value $1. 



5.3.3 Sapling Files 

A sapling file (see Figure 5-9) is a standard file that contains more than 
51 2 and no more than 128K bytes ($200 < EOF <= $20000). A sapling file 
comprises an index block and 1 to 256 data blocks. The index block 
contains the block addresses of the data blocks. 
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■ 

I 



key_pointer 

$200 < EOF < $20000 




data 




data 


block $00 




block $01 



Index Block: 
up to 256 2-byte 
pointers to data blocks. 



data 
block $FE 



data 
block $FF 



Figure 5-9. Structure of a Sapling File 



The key block of a sapling file is its index block. SOS retrieves data blocks 
in the file by first retrieving their addresses in the index block. 

The storage_type field of an entry that points to a sapling file has the 
value $2. 



5.3.4 Tree Files 



A free file (see Figure 5-10) contains more than 1 28K bytes, and less than 
16M bytes ($20000 < EOF < $1000000). A tree file consists of a master 
index block, 1 to 128 subindex blocks, and 1 to 32,768 data blocks. The 
master index block contains the addresses of the subindex blocks, and 
each subindex block contains the addresses of up to 256 data blocks. 



key_pointer »■ 

$20000 < EOF < $1000000 



$00 ' $01 ' '$7El$7F 

master index block 
I I I I 



Master Index Block: 
up to 128 2-byte pointers 
to index blocks. 



/ 



/ 



$00 1 $01 1 1 $FE 1 $FF 
index block $00 
1 1 1 1 




$001 $01' l$FEl$FF 

index block $7F ~ 
1 1 1 1 





/ / 



data 




data 




data 




data 


block $00 


• • • • 


block $FF 




block $00 


• • • • 


block $FF 



Figure 5-10. The Structure of a Tree File 
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The key block of a tree file is the master index block. By looking at the 
master index block, SOS can find the addresses of all the subindex 
blocks; by looking at those blocks, it can find the addresses of all the 
data blocks. 

The storage_type field of an entry that points to a tree file has the value $3. 

5.3.5 Sparse Files 

A sparse file is a sapling or tree file in which the number of data bytes that 
can be read from the file exceeds the number of bytes physically stored in 
the data blocks allocated to the file. SOS implements sparse files by 
allocating only those data blocks that have had data written to them, as 
well as the index blocks needed to point to them. 

For example, we can define a file whose EOF is 16K, that uses only three 
blocks on the volume, and that has only four bytes of data written to it. 
Create a file with an EOF of $0. SOS allocates only the key block (a data 
block) for a seedling file, and fills it with null characters (ASCII $00). 

Set the EOF and marl< to position $0565, and write four bytes. SOS 
calculates that position $0565 is byte $0165 ($0564 - $0200 * 2) of the 
third block (block $2) of the file. It then allocates an index block, stores 
the address of the current data block in position of the index block, 
allocates another data block, stores the address of that data block in 
position 2 of the index block, and stores the data in bytes $0165 through 
$0168 of that data block. The EOF is $0569. 

Set the EOF to $4000 and close the file. You have a 16K file that takes 
up three blocks of space on the volume: two data blocks and an index 
block. You can read 16384 bytes of data from the file, but all the bytes 
before $0565 and after $0568 are nulls. Figure 5-1 1 shows how the file 
is organized: 
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key^pointer 

^\ 012 



Key Block 



Data 
Blocks 




bytes $565.. $568 



Figure 5-11. A Sparse File 

Thus SOS allocates volume space only for those blocks in a file that 
actually contain data. For tree files, the situation is similar: if none of the 
256 data blocks assigned to an index block in a tree file have been 
allocated, the index block itself is not allocated. 



On the other hand, if you CREATE a file with an EOF of $4000 (making it 
16K bytes, or 32 blocks, long), SOS allocates an index block and 32 data 
blocks for a sapling file, and fills the data blocks with nulls. 

The first data block of a standard file, be it a seedling, sapling, or 
tree file, is always allocated. 




If you read a sparse file, then write it, the copy will not be sparse: 
all the phantom blocks will be written out as blocks full of nulls. 
The Apple III System Utilities program, on the other hand, can 
distinguish between sparse files and non-sparse files and make a 
sparse copy of a sparse file. Backup III also handles sparse files 
correctly, but it should not be used to make copies, because 
when it backs up a file, it clears the file's backup bit, so that a 
backup of all modified files will overlook the sparse file. 



5.3.6 Locating a Byte in a Standard File 

The mark is a three-byte pointer that is normally used to specify a logical 
byte position within a standard file, using the standard model of a block 
file. It can also be used to pinpoint the block number and byte number 
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within that block where that byte can be found on a volume. To do so, the 
mark is divided into three fields, shown in Figure 5-12: 



Bit 
mark 



23 



17 16| 



n — I — I — I — I — r 
index_block 



~i — I I I I r 
clata_biock 

I I I ~ I 1 L. 



1 — I — I — I — I — I — r 
byte 

_J J I I I I L. 



Used by 



Tree only 



Tree, sapling 



All tlnree 



Figure 5-12. Format of mark 



Index block (7 bits): 

If the file is a tree file, this field tells which subindex block points to the 
data block. If / = index_block, the low byte of the subindex block address 
is at byte / of the master index block; the high byte is at byte (/+$100). 

data_biock (8 bits): 

If the file is a tree file or a sapling file, this field tells which data block is 
pointed to by the selected index block. If / = data_block, the low byte of the 
data block address is at byte / of the index block; the high byte is at byte 
(/■ + $100). 

byte (9 bits): 

For tree, sapling, and seedling files, this field tells the absolute position of 
the byte within the selected data block. 

This format for mark applies to SOS 1 .2. Future versions of SOS 
may use indexing schemes that divide the 24 bits differently If an 
interpreter uses mark as a three-byte pointer to a logical byte 
position in a file, it will be unaffected by such changes; if it 
meddles with index blocks, it may fail catastrophically trashing 
your disk in the process, under some future version of SOS. 



5.4 Chapter Overview 



The following figures summarize the information in this chapter. 

• Figure 5-13, Disk Organization, shows disk layout and directory 
structure. 

• Figure 5-14, Header and Entry Fields, explains the individual 
fields in the preceding figure. 
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BLOCKS ON A VOLUME 
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loader 


loader 


directory 




directory 


bit map 




bit map 
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Any Block 



pointer 
header 



more 
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more 
ir" entries 
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entries 
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linked by pointers. 
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directory file and its 
contents. 
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directory 



HEADER 
VOLUME DIRECTORY 
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HEADER 
SUBDIRECTORY 
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Field 
length 



Byte of Field 
Block Length 



FILE ENTRY 
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Block Length Offset 
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5 bytes 


^ fltename ^ 


$05 
$13 


1 5 bytes ^ 


? (Henafne ^ 


$05 
$13 
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SUBDIRECTORY FILE: storage. type = $D 



J H 



SEEDLING FILE: storagejype = $1 



$0 < EOF ■ S200 



data 
block 



Data Block 
512 bytes long 



SAPLING FILE: storage.type = $2 

key pointer 

S200 EOF 
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\ 


data 




data 
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Figure 5-13. Disk Organization 
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byte 1 

7 6 5 4 3 2 1 



creation 
lastmod 

(4 bytes) 



"1 — I — I — I — I — r 

year 

J I I I I L 



bytefl 

,76543210 
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byte 3 



storage type 

(4 bit's) 



access 

(1 byte) 



$0 = inactive file entry 

$1 = seedling file entry 

$2 = sapling file entry 

$3 = tree file entry 

$D = subdirectory file entry 

$E = subdirectory header 

$F = volume directory fieader 



fiie type 

(1 byte) 



$00 = typeless file 

$01 = bad block file 

$02 = Pascal or assembly code file 

$03 = Pascal text file 

$04 = Basic text; Pascal ASCII file 

$05 = Pascal data file 

$06 = General binary file 

$07 = Font file 

$08 = Screen image file 

$09 = BASIC program file 

$0A = BASIC data file 

$0B = Word Processor file 

$0C = SOS system file (DRIVER, INTERR KERNEL) 

$0D = Reserved 

$0E = Reserved 

$0F = Directory file 

$10-$BF = SOS reserved 

$C0-$FF = ProDOS reserved 



byte 2 



r 



D 


RN 


B 


RESERVED 


W 


R 



Write-enable 
Read-enable 



Backup 

Rename-enable 

Destroy-enable 



namejength = length offile name ($1-$F) 

lile_name = $1-$F ASCII characters: first = letters 
rest are letters, digits, periods- 

key_pointer = Block address of file's key block 

block5_used = total blocks for file 

EOF = byte number for end of file ($0-$FFFFFF) 

version, min version = for SOS 12 

entry lenglh = $27 for SOS 1 2 

entries_per_block = $0DforSOS 1.2 

aux type - defined by interpreter 

file_count - total files in directory 

bit _map_ pointer = block address of bit map 

total_blocks ^ total blocks on volume 

parent_pomter - block address containing entry 

parent_entry_number = number in that block 

parent entryjength ^ $27 for SOS 12 

header_pointer - block address of key block 
of entry's directory. 



Figure 5-14. Header and Entry Fields 
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6. 1 Interrupts and E vents 



An interrupt is a signal from a peripheral device to the CPU. When the 
CPU receives an interrupt, it transfers control to SOS, which saves the 
current state of the executing program and calls an interrupt handler, 
located in the driver of the interrupting device. After the interrupt is 
handled, control is returned to the program that was interrupted. 

Interrupts allow device drivers to operate their devices asynchronously. 
By using interrupts, a device can operate more efficiently and allow the 
interpreter to continue running while a long I/O operation is in progress. 
For example, when you send a long buffer of text to the .PRINTER driver, 
the driver does not process the text ail at once; instead, it immediately 
returns control to the interpreter, and the interpreter can do something 
else while the interrupt-driven .PRINTER driver processes the buffer 
for output. 

The Apple 1 1 I/SOS system fully supports interrupts from any internal or 
external peripheral device capable of generating them. To use the system 
efficiently, an interpreter must be designed to work properly even if 
interrupted. Thus, the interpreter cannot contain any time-dependent 
code (such as timing loops), except to provide a guaranteed 
minimum time. 

Interrupts are discussed in detail in the Apple III SOS Device Driver 
Writer's Guide. 

Interrupts are ranked in priority by the priorities of the devices on which 
they occur. Each device has a unique priority, assigned at system 
configuration time. In addition, when an interrupt occurs on a device, all 
further interrupts from that device are locked out until that interrupt has 
been fully processed. For these reasons, SOS never has to deal 
simultaneously with two interrupts of equal priority Conflicts between 
interrupts of different priorities are resolved in favor of the higher priority: 
a higher-priority interrupt can suspend processing of a lower-priority 
interrupt, but not vice versa. 
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SOS also supports the detection and handling of events. An event is a 
signal from a device driver to an interpreter that something of interest to 
the interpreter has happened. When an event of sufficient priority occurs, 
SOS suspends the interpreter and saves its state, then calls an event 
handler to process the event, then returns control to the portion of the 
interpreter that was suspended. By using events, an interpreter can 
respond to outside occurrences without spending all its time watching 
out for them. 

The most common kind of event is triggered by a software response to a 
hardware interrupt: a device driver (such as the .CONSOLE driver) defines 
a certain occurrence (such as a press of the space bar) as an event, and 
allows interpreters or assembly-language modules to respond to that 
event. In principle, however, events need not be triggered by interrupts: an 
event can signal, for example, an overflow on a communication card, a 
"message received" condition on a network interface, or a "new volume 
mounted" condition on a mass-storage device. Any occurrence or 
condition a driver can detect can be signaled as an event. 

SOS currently supports two events, both detected by the 
.CONSOLE driver: the Any-Key Event and the Attention 
Event. Both of these are produced by interrupts from the 
keyboard. These events are described in the Apple III Standard 
Device Drivers Manual. Additional events may be defined 
by a device driver: for details, see the Apple III SOS Device Driver 
Writer's Guide. 

The most common event sequence is illustrated below. An event is 
armed when the interpreter prepares a device driver to signal a certain 
occurrence (in this case, a keypress) as an event. The interpreter supplies 
the address of a subroutine to be called when the expected event occurs. 

When the device driver detects the event (in this case, by means of an 
interrupt), the driver places the event into a queue and returns to the 
interrupted process, whether interpreter or SOS. This is illustrated by 
Figure 6-1 . 
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queue 
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Figure 6-1. Queuing An Event 

Any time SOS is ready to return control to the interpreter, such as after 
executing a call or processing an interrupt, it checks the event queue. If 
it finds an event of a priority above the preset event fence (see Figure 6-2), 
SOS calls an event-handler subroutine within the interpreter When the 
event has been processed, SOS returns control to the main body of the 
interpreter 

case A: priority > fence 







interpreter 


event 
handler 



SOS 







driver 


interrupt 
handler 



process 
event 



return to 
interrupted code 



Figure 6-2. Handling An Event: Case A 
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If SOS finds no event above the fence (see Figure 6-3), the event remains 
queued until the fence is set (by a SET_FENCE call) below the event's 
priority. Then, the event will be processed as soon as the call is 
completed. 



case B: priority < fence 







interpreter 


event 
handler 



SOS 







driver 


interrupt 
handler 



return to 
interrupted code 



event remains 
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is not 
processed 



SOS call : set fence < priority 



process 
event 



return to code 
following SOS call 




Figure 6-3. Handling An Event: Case B 

An event need not be triggered by an interrupt: it can occur 
as a result of any operation within a device driver But events are 
detected only by device drivers, and are handled only by an 
event-handler subroutine within an interpreter An event handler 
will be called only after a SOS call or an interrupt is processed. 
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6.1.1 A rming and Disarming E vents 

SOS has not defined a uniform mechanism for arming and disarming 
events: this is left up to the device driver that supports the event. The two 
existing events are armed and disarmed by D_CONTROL calls to the 
.CONSOLE driver 

An interpreter arms an event by passing three items to the device driver: 
the address of the event handler, a one-byte event identifier (ID), and a 
one-byte event priority. The event ID indicates the nature of the event, and 
allows the event handler to distinguish different events. For example, the 
event ID for the Any-Key Event is 1 ; the event ID for the Attention Event is 
2. The event priority indicates the importance of the event, and determines 
when, or whether, the event will be processed. 

An interpreter disarms an event by arming it with a priority of zero: this 
ensures that it will be ignored. 

6. 1.2 Tiie Event Queue 

More than one event can be armed at once, and more than one event can 
occur during a driver's operation. SOS has a priority-queue scheme for 
keeping simultaneous events in order. 

When a driver detects an event, it assigns an ID, a priority, and an event- 
handler address to the event. (These are the values the interpreter passed 
to the driver when the event was armed.) The ID, priority, and address are 
placed in an event queue (see Figure 6-4) maintained by SOS. 
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Second 



Third 



Last 



Figure 6-4. The Event Queue 

The queue is arranged in order by priority: an event of higher priority will 
be handled first. The highest priority is $FF: this priority guarantees that 
an event will be handled before any other event. Events of equal priority 
are queued first-in, first-out (FIFO): an event with the same priority as 
another event already in the queue is placed after the other event. Events 
of priority $00 can never be handled, so they are not queued. 



6. 1.3 Tlie Event Fence 

The priority ordering of the event queue determines not only when an 
event will be handled, but also whether it will be handled at all. SOS 
maintains an event fence (see Figure 6-5) that determines which events 
will be processed and which will not. 

The fence is a value from $00 to $FF that is compared to the priority value 
of each event in the queue. Only those events whose priority is greater 
than the fence will be handled: setting the fence to $FF ensures that no 
events will be handled. 
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$FF 



$20 



$1F 



First 



Second 



Third 



$0F 



$09 



Not Processed 



fence = $10 



Figure 6-5. The Event Fence 

All events above the fence are handled, in order, and removed from the 
queue before SOS returns control to the suspended portion of the 
interpreter Events below the fence remain in the queue, and may be 
handled when the fence is lowered. 

Two SOS calls, SET_FENCE and GET_FENCE, allow an interpreter to set 
and read the value of the fence. If the interpreter lowers the fence while 
events are in the queue, previously queued events whose priority values 
are greater than or equal to the new value of the fence will be handled 
immediately after the call is completed. 



6.1.4 Event Handlers 

An event handler is a subroutine in the interpreter that is called by SOS in 
response to an event, under certain conditions. An event can only be 
processed when the interpreter is executing. If a SOS call is being 
executed when an event occurs, the event is queued; after the call is 
executed, SOS will call the interpreter's event handler if the event's priority 
is higher than the event fence. When the event handler is called, the 
previous state of the machine is stored on the interpreter's stack, and the 
event ID byte is stored in the accumulator; then the event is deleted from 
the queue. 



■ 
■ 
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Among the items saved on the stack is the current value of the event 
fence. The fence is then raised to the level of the current event until the 
event has been processed: this ensures that no event of lower priority will 
preempt the current event, now that the current event is no longer in the 
queue. Figure 6-6 illustrates the system status during event handling. 



event Id 




s + 

s + 1 






fence 


s + 2 


SOS 




return 


s + 3 


address 


s + 4 







PHA 
PLA 



Figure 6-6. System Status during Event Handling 

The event handler uses the event ID to determine the reason it was called 
and to take appropriate action. 



When the event handler is finished, it returns control to SOS via an RTS; 
SOS then restores the system to its previous state, and returns control to 
the suspended portion of the interpreter. Since the previous state included 
the event fence, any fence set by the event handler will be lost, unless that 
fence value is passed to the body of the interpreter and reestablished 
by it. 
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6. 1.5 Summary of Interrupts and Events 

• Interrupts are generated by hardware; events are generated by 
software. 

• Interrupts are ranked by the priorities assigned to the devices 
they occur on; events are ranked by the priorities assigned to 
them by the drivers that detect them. 

• Interrupts are stacked; events are queued. 

• Interrupts are handled by an interrupt handler in a device driver; 
events are detected and queued by a device driver, and 
processed by an event handler in the interpreter 

• Interrupts can preempt the interpreter or SOS; events can only 
preempt the interpreter 

• Interrupts cannot be disabled by the interpreter; events can be 
disabled by setting the event fence to $FF. 

6.2 Resources 



The Apple III has two resources accessible by special SOS calls: the 
system clock and the analog ports. 

6.2.1 The Clock 

The Apple 1 1 1 system clock runs continuously: when the computer is 
turned off, the clock runs on batteries. It keeps time down to the 
millisecond, and can be read and set by SOS. 

The clock is set and read by two calls: SET_TIME and GET_TIME. To set 
the time, the calling program writes it as an ASCII string into an 18-byte 
buffer in memory, then passes SOS the address of the buffer: SOS then 
sets the clock to the specified time. To read the time, the calling program 
passes SOS the address of an 18-byte buffer: SOS then writes the current 
time into this buffer 



■ 
■ 
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If the computer has no functioning clock, SOS responds to a SET_TIME 
call by saving the time it receives. SOS returns this time unchanged upon 
a subsequent GET_TIME call. 

Both calls express the time as an 18-byte ASCII string of the following 
format: 

YYYYMMDDWHHNNSSUUU 
The meaning of each field is as below: 



Field 


Meaning 


IMinimum 


IMaximum 


YYYY 


Year 


1900 


1999 


MM 


Month 


00 


12 December 


DD 


Date 


00 or 01 


28, 30, or 31 


W 


Day 


01 Sunday 


07 Saturday 


HH 


Hour 


00 Midnight 


23 11:00 p.m. 


NN 


Minute 


00 


59 


SS 


Second 


00 


59 


UUU 


Millisecond 


000 


999 



For example, Monday, December 29, 1980, at 9:30 a.m. would be specified 
by the string "198012290093000000". 

On input, SOS replaces the first two digits of the year with "19" and 
ignores the day of the week and the millisecond. SOS calculates the day 
from the year, month, and date. 

SOS does not check the validity of the input data. The clock rejects any 
invalid combination of month and date. February 29 is always rejected. 

The clock does not roll over the year 



6.2.2 The Analog Inputs 

The GET_ANALOG call reads the analog and digital inputs from an 
Apple 1 1 1 Joystick connected to port A or B on the back of the Apple lll.lt 
can also read compatible signals from other devices. 
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6.2.3 TERMINATE 

The TERMINATE call provides a clean exit from an interpreter 
It clears memory, clears the screen, and displays the message INSERT 
SYSTEM DISKETTE AND REBOOT on the screen. The TERMINATE call 
is useful as part of a protection scheme that locks out the NMI. Such a 
scheme allows only one way of leaving the program, and erases it 
completely afterward. 

Before using this call, an Interpreter must close all open files. This 
will ensure that no half-written buffers are left in limbo. 



6.3 Utility Calls 



These calls deal with the system clock/calendar, the event fence, the 
analog input ports, and other general system resources. The name of 
each call below is followed by its parameters (in boldface). The input 
parameters are directly-passed values and pointers to tables. The output 
parameters are all directly-passed results. The SOS call mechanism is 
explained in Chapter 8; the individual calls are described fully in Chapters 
9 through 1 2 of Volume 2. 

SET_FENCE 
fence: value 

This call changes the current value of the user event fence to the value 
specified in the fence parameter. Events with priority less than or equal to 
the fence will not be serviced until the fence is lowered. 



GET_FENCE 
fence: result 

This call returns the current value of the user event fence. 



SET_TIME 
time: pointer 

This call sets the current date and time. SET_TIME attempts to set the 
hardware clock whether it is operational or not. It also stores the new time 
in system RAM as the last known valid time: this time will be returned by 
all subsequent GET_TIME calls if the hardware clock is absent or 
malfunctioning. 

GET_TIME 
time: pointer 

This call returns the current date and time from the system clock. If the 
clock is not operating, it returns the last known valid date and time from 
system RAM. If the system knows no last valid time, GET_TIME returns a 
string of 18 ASCII zeros. 

GET_ANALOG 

joy mode: value; joy status: result 

This call reads the analog and digital inputs from an Apple III Joystick 
connected to port A or B on the back of the Apple III. 

TERMINATE 

This call zeros out memory, clears the screen, displays INSERT SYSTEM 
DISKETTE & REBOOT in 40-column black-and-white text mode on the 
screen, and hangs, until the user presses CONTROL-RESET to reboot the 
system. This call uses no parameters. 
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This chapter describes the two kinds of assembly-language programs that 
you can use: interpreters and modules. It discusses their structures, 
operating environments, and special characteristics; it explains how to 
create them and how to get them successfully loaded into the system. 

7.1 Interpreters 



The interpreter is the assembly-language program that SOS loads into 
memory from the file SOS.INTERP and executes at boot time. The 
interpreter can be a stand-alone interpreter, like Apple Writer III, or it can 
be a language interpreter, like the BASIC and Pascal interpreters. A 
stand-alone interpreter, normally an application program, provides the 
interface between you and SOS. A language interpreter can either provide 
this interface directly, as does BASIC, or support a program that does, as 
does Pascal, or both. A language interpreter can load and run your 
program in response to your command, or it can load and run a greeting 
program at boot time. 

The interpreter is stored in its entirety in the file SOS.INTERP in the 
volume directory of the boot diskette. Additional functions can be added 
to the interpreter by use of assembly-language modules (see section 7.4). 

An interpreter can 

• Make SOS calls; 

• Store and retrieve information in memory; and 

• Handle events. 

The SOS calls made by an interpreter can interact with you through 
devices, store or retrieve data, or request memory segments in which to 
store data. The memory accesses made by an interpreter can manipulate 
any information in the memory segments owned by the interpreter The 
events handled by the interpreter can let it respond to special 
circumstances detected by device drivers. 



I 
I 
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7.1.1 Structure of an Interpreter 

An interpreter is stored in a file named SOS.INTERP in the volume 
directory of a boot diskette. The data in this file consists of two parts: 
a header and a part containing code — as shown in Figure 7-1 . 



8 bytes 



2 bytes 



m bytes ^ 




header 
part 



2 bytes 



loading ^address 



2 bytes 



code_length = n 



n bytes 



code part 



Figure 7-1. Structure of an Interpreter 
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The header consists of five fields, described below: 
label (8 bytes): 

This field contains eight characters 
SOS NTRP 

including the space. This is a label that identifies this file as an interpreter. 
The letters are all uppercase ASCII with their high bits cleared. 

opt_heacler_length (2 bytes): 

The next field contains the length of an optional header information 
block: if no optional header block is supplied, these bytes should 
be set to $0000. The length does not include the two bytes of the 
opt header length field itself. 

opt header (opt header length bytes): 

If the previous field is nonzero, the optional header block comes here, 
loadingaddress (2 bytes): 

This field is the loading address (in current-bank notation) of the code 
part that must go into the highest bank of the system. 

code_length (2 bytes): 

This field is the length in bytes of the code part, excluding the header. 

For example, an interpreter that begins at location $9250 in the highest 
bank of the system, is $25AF bytes long, and has no optional header 
would have a header part like this: 

.ASCII "SOS NTRP" ; label for SOS. INTERP 

.WORD 0000 ; opt_header_length = 

.WORD 9250 ; ioading_address 

.WORD 25AF ; code_length 



Interpreters are always absolute code, and must start at a fixed 
location. A program In relocatable format cannot be used as an 
interpreter 
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The header is immediately followed by the code part of the interpreter. 
During a system bootstrap operation, the code part is placed at the 
address given in the header, so that the first byte of code resides in the 
location specified by loading_address (location $2:9250 for the above 
example, in a 128K system). When loading is completed, execution 
of the interpreter begins at this location: the header part is discarded. 

SOS requires only that the first byte of the code part be executable 
interpreter code; the rest of the code part of the interpreter may 
be in any format. 

7.1.2 Obtaining Free Memory 

An interpreter can use any and all memory that is not already allocated 
to SOS or device drivers, but first it must request this memory from SOS. 
The REQUEST_SEG and FIND_SEG calls to SOS can be used by an 
interpreter to request an area of memory in which to store data. 

By allocating a segment of memory for its exclusive use, the interpreter 
ensures that no other code— the SOS file system, a device driver, an 
invocable module— will use that segment for another purpose. SOS 
allocates by an honor system: it protects allocated memory from conflict, 
but cannot prevent the use of unallocated memory. You can avoid 
memory conflict entirely by always allocating memory before use and 
deallocating it after use. 

Using unallocated memory can have dramatic results. When an 
interpreter overwrites a file's I/O buffer, the system crashes. It 
does so to avoid trashing a disk: since the buffer contains block- 
allocation information as well as the Interpreter's data, SOS would 
compromise the entire disk if it wrote out a buffer altered by the 
interpreter To avoid this, SOS comes down with a SYSTEM 
FAILURE 16 message. When this happens, the data in the I/O 
buffer, as well as the data in memory, are lost. 

The piece of interpreter code given below uses the FIND_SEG call 
(described in Chapter 12 of Volume 2) and the segment-to-extended 
address conversion described in section 2.2.3.1 . It requests a 1 K segment 
of memory (consisting of four adjacent memory pages) and fills that 
segment with zeros. 
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The first part of this procedure is the call to SOS to find a segment of the 
appropriate size. This is done with a FIND_SEG call. 



FINDSEG 


.EQU 


041 




FINDIT 


BRK 




Perform the SOS call 




.BYTE 


FINDSEG 


FIND_SEG 




.WORD 


FSPARAMS 


with the required parameters here. 




BEQ 


CONVERT 


IF successful, THEN process addresses. 




LDA 


PAGES 


ELSE see how big it can be. 




BNE 


FINDIT 


IF any free memory exists, THEN ask again. 




JMP 


ERRORHALT 


ELSE stop execution. 


FSPARAMS 










.BYTE 


06 


Six parameters for FIND_SEG: 


SRCHMOD 


.BYTE 


00 


Seg must be in one bank 


SEGID 


.BYTE 


11 


I'll call it seg. 11. 


PAGES 


.WORD 


04 


Ask for 1 K of memory 


BASE 


.WORD 


0000 


"base" result parameter 


LIMIT 


.WORD 


0000 


"limit" result parameter 


SEGNUM 


.BYTE 


00 


"seg.num" result parameter 


EXTLIMIT 






Place to store (extended form of) 




.WORD 


00 


limit bank and page. 



Once the FIND_SEG call succeeds, the values at BASE and LIMIT contain 
addresses in segment-address form of the first and last pages in the 
segment. Now the base and limit addresses must be converted into 
extended form to be used in clearing the memory in that segment. The 
first part of this process is determining where the segment is located: in 
the S-bank, in bank 0, or in another bank in bank-switched memory. 



CONVERT 



LDA 
BEQ 
CMP 
BEQ 
CMP 
BEQ 



BASE 

SZBANK 

#0F 

SZBANK 
#10 

SZBANK 



Get bank number of segment 
Is it in bank 0? 
Is it in low S-bank? 

Is it in high S-bank? 



For the general case (any bank but S or 0), the conversion involves 
calculating the proper X-byte and creating the two-byte address 
for the pointer. 



I 
I 
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ANYBANK 



CLC 




Turn bank number into X-byte 


ADC 


#7F 


XX = $80 + bb - 1 


STA 


1651 


Store it in X-page for pointer. 


LDA 


BASE + 1 


Get page number in bank 


CLC 




Turn into high part of address 


ADC 


#60 


NNNN:=pp00 + $6000 


STA 


51 


Store into zero-page pointer 


LDA 


#00 


Create low part of $00 


STA 


50 


Store into zero-page pointer 


LDA 


LIMIT 


Get bank number of segment. 


CLC 




Turn into X-byte. 


ADC 


#7F 


XX = $80 + bb - 1 


STA 


EXTLIMIT 


Store it in X-page for pointer 


LDA 


LIMIT + 1 


Get page number of limit. 


CLC 




Turn into extended form for 


ADC 


#60 


later comparison with page 


STA 


EXTLIMIT + 1 


being zeroed. 


JMP 


CLEARIT 


and proceed to clear the segment. 



For the case where the segment resides in bank or the S-bank, the 
conversion is much easier: just use an X-byte of $8F and create the proper 
two-byte address. 



SZBANK 



LDA 


#8F 


; Use an X-byte of $8F 


STA 


1651 




LDA 


BASE + 1 


; Get page number in bank 


STA 


51 




LDA 


#00 


; Create low part of $00 


STA 


50 




LDA 


#8F 


; Use limit X-byte of $8F 


STA 


EXTLIMIT 




LDA 


LIMIT + 1 


; Convert page number of limit 


STA 


EXTLIMIT + 1 


; to extended form. 



Now an extended pointer has been created and is stored in locations 
$0050, $0051, and $1651. This pointer indicates the beginning of the 
memory range allocated by SOS in the FIND_SEG call. 

A process similar to the above can be used to convert the limit segment 
address into another extended pointer to define the end of the segment. 

Remember that the limit address specifies the last page In the 
segment. Converting the limit address into a pointer using the 
method shown above will give you a pointer to the beginning of 
this page, not the end. Keep this in mind when comparing two 
pointers derived from base and limit segment addresses. 
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P 
I 



Once the pointers are set up, a simpler form of the increment loop 
described in section 2.4.2.1 can be used to scan through every location 
in the segment and, in this example, set each byte to $00. Because the 
FIND_SEG call requested that the entire segment reside in one bank, 
the increment loop does not need to increment the X-byte of the pointer, 
or compare the base X-byte to the limit X-byte. 



LDY 


#00 


Use Y as an index in each page 


LDA 


#00 


Value to put in each location. 


STA 


(50),Y 


Extended-address operation. 


INY 




Do next byte in page. 


BNE 


STORE 




INC 


51 


Move to next page. 


LDA 


51 


Get high part of address. 


CMP 


EXTLIMIT + 1 


Compare with high part of limit 


BCC 


STORE 


If pointer.high < = limit.high, 


BEQ 


STORE 


clear another page. 



A program that wishes to use more than 32K bytes of memory must 
handle the incrementing and comparing of X-bytes in a loop like this: 



STORE 



CHECK 



LDY 


#0 


Use Y as an index in each page 


LDA 


#0 


Value to put in each location. 


STA 


(50),Y 


Extended-address operation. 


INY 




Do next byte in page 


BNE 


STORE 




INC 


51 


Move to next page 


BNE 


CHECK 


If same banl<, check limit 


LDA 


#80 


else 


STA 


51 


set page to $80 


INC 


1651 


and increment X-byte 


LDA 


1651 


Compare X-byte to 


CMP 


EXTLIMIT 


limit X-byte 


BCC 


STORE 


If less than, clear page 


LDA 


51 


else compare page 


CMP 


EXTLIMIT + 1 


to limit page 


BCC 


STORE 


If less than 


BEQ 


STORE 


or equal, clear page 
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7. 1.3 Event Arming and Response 

To arm an event, an interpreter may pass the starting address of its event 
handler to a device driver that can detect the event. When the event 
occurs, the interpreter's event handler w^ill be called. One way to arm an 
event is by a D_CONTROL call to a device driver. 

For example, assume that the .CONSOLE device driver defines a certain 
keypress as an event. An interpreter that wishes to use this feature would 
include a subroutine that is to be called each time that key is pressed. The 
interpreter would make a D_CONTROL call to the .CONSOLE driver, 
passing it the ASCII code of the keypress to detect and the address of the 
event handler. When the key is pressed, the console queues the event 
handler's address, and SOS calls the event handler to handle the 
keypress. 

The D_CONTROL calls that arm an event for a given device driver are 
described in the documentation accompanying that driver. For the 
.CONSOLE events, see the Apple III Standard Device Drivers Manual. 

7.2 A Sample Interpreter 



This section illustrates the design and construction of a very simple 
interpreter. The example is simple, but has all the parts an interpreter 
must have. It shows how SOS calls are made (see Chapter 8 for a full 
explanation), and how events are handled. The complete listing of the 
interpreter is shown in the next section; in this section we explain 
portions in detail. 

This nnodel is intended for demonstration only It does not fully 
show all features of SOS (such as mennory allocation) available to 
an interpreter, nor does it contain connprehensive error-checking 
and debugging aids. Use this model only to gain insight into the 
construction of an interpreter; please do not base your own 
designs upon it. 

This program, SCREENWRITER, reads a byte from the keyboard, then 
writes it out to the screen, without filtering out control characters. It writes 
explicitly, without using screen echo. 
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The interpreter contains an event mechanism. When CONTROL-Q is 
read, the console driver detects it as an event. The event is processed 
when control next returns to the interpreter. If the character typed before 
the CONTROL-Q is ESC, the event handler beeps thrice and issues a 
TERMINATE call; if not, the event handler just beeps thrice. 

This interpreter is deliberately inconsistent in style, in order to show 
different ways of coding SOS calls. Some calls are coded in line; some, 
as subroutines. Some are coded with a macro, SOS; some are not. The 
macro itself can use the SOS call number, or the number can be given 
the name of the call, via an .EQUate statement. 



The syntax for a SOS call using the SOS macro is 
SOS call_num, parameter list pointer 



For example, the call 



SOS READ, READLIST 



uses the label READ, which has been defined as $CA by an .EQUate. This 
call could also have been coded as 



SOS 0CA, READLIST 



READLIST is a pointer to the required parameter list. In this sample 
interpreter, the required list precedes the call, as the Apple III Pascal 
Assembler accepts backward references more readily than forward 
references. 



Here is the macro definition for a SOS call block: 



.MACRO 
BRK 
.BYTE 
.WORD 
■ ENDM 



SOS 

%1 
%2 



; Macro def for SOS call block 
; Begin SOS call block 
; calLnum 

; parameter_list pointer 
; end of macro definition 
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After the header and parameter lists for various calls (shown in the 
complete listing, but not in this section), comes the main interpreter 
program, which is in two sections. The first section, the initialization 
block, opens the console and gets its dev_num; turns off screen echo; 
passes its ref_num and dev_num to subroutines; arms the attention 
event; and sets the fence. 



BEGIN 



.EQU 

JSR 

JSR 

JSR 

JSR 

SOS 



LDA 
STA 
STA 



OPENCONS 
GETDNUM 
SETCONS 
ARMCTRLQ 
60, FENLIST 



REF 

RREF 

WREF 



Open .CONSOLE 
Get dev_num 
Disable echo 
Arm attention event 
Set event fence to 0: 
here we coded "60" directly 

Set up ref_num 
for reads 
and writes 



The main program loop uses a two byte I/O buffer, the second byte of 
which is always a line feed (LF). The main program reads a byte from the 
keyboard into the first byte of the I/O buffer, then checks whether that 
byte is a carriage return (CR): if so, both bytes in the buffer will be written; 
if not, only the first byte will be written. This is done by setting the value of 
the write count (WONT in the listing, or bytes in the call definition) to 2 or 
1 , respectively The loop repeats indefinitely; the only exit from the 
program is through the event-handler subroutine, HANDLER. 



The numbers preceded by a dollar sign, like $010, are local labels. The 
numbers are decimal, not hex. 



SOS 


READ, RCLIST 


; Read In one byte: 






; here we used READ for 0CA 


LDA 


RCNT 


; IF no bytes were read 


BEQ 


$010 


; THEN go read again 


STA 


WCNT 


; Set up write count 


LDA 


BUFFER 




CMP 


#0D 


; IF first byte in buffer Is CR 


BNE 


$020 


; THEN write out LF also 


INC 


WCNT 





$020 SOS WRITE, WPLIST ; Write out 1 or 2 bytes 

JMP $010 ; Repeat ad infinitum 
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The first subroutine is OPENCONS, which opens the .CONSOLE file for 
reading and writing. It consists of a single SOS OPEN call, and is coded 
with the parameter lists preceding the call block, which here is coded 
without a macro. 



COLIST 
CREF 

COPLIST 
OPENCONS 



.BYTE 04 
.WORD CNAME 
.BYTE 00 
.WORD 
.BYTE 



COPLIST 
01 



.BYTE 03 



BRK 

.BYTE 008 

.WORD COLIST 

LDA CREF 

STA REF 
RTS 



4 required parameters for OPEN 
pathname pointer 
ref_num returned here 
optlon_list pointer 
length of opt parm list 

Open for reading and writing 



Here we didn't use a macro. 
Begin SOS call block 
Open the console. 
Pointer to parameter list 
Save the result ref_num 
for READS and WRITEs. 



The next subroutine, GETDNUM, which returns the dev num of 
.CONSOLE, is coded similarly, except that it has no optional 
parameter list. 



The SETCONS subroutine suppresses screen echo on the .CONSOLE 
file. This is a very simple example of a D_CONTROL call, as the control 
list is only one byte long; the next is more complex. 



SETLIST .BYTE 03 

CNUM .BYTE 00 

.BYTE 0B 

.WORD CONLIST 

CONLIST .BYTE FALSE 



3 required parms for D_CONTROL 
dev_num of .CONSOLE 
controLcode = 0B: screen echo 
control.list pointer 

Disable screen echo 



SETCONS 

LDA CONSNUM ; Set up device number 

STA CNUM ; of .CONSOLE 

SOS D_CNTL, SETLIST 
RTS 
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The ARMCTRLQ subroutine arms the Attention Event for CONTROL-Q. 
The D_CONTROL call in this subroutine sends the event priority, event 
ID, event-handler address, and the attention character code to the 
.CONSOLE driver. 



DCLIST 
DNUM 



CLIST 



BANK 



ARMCTRLQ 



.BYTE 

.byte 

.BYTE 



LDA 
STA 
LDA 
STA 
SOS 
RTS 



03 
00 
6 



.WORD CLIST 



.BYTE 0FF 

.BYTE 02 

.WORD HANDLER 

.BYTE 00 

.BYTE 11 



BREG 
BANK 
CONSNUM 
DNUM 

D_CNTL, DCLIST 



3 required parms for D_CONTROL 
dev_num of .CONSOLE goes here 
controLcode = 06: 

Arm Attention Event 
controLlist pointer 

Control list 
Event priority 
Event ID 

Event handler address 
Event handler bank 
Attention character = CTRL-Q 

Set up bank number 

of event handler 
Set up device number 
for control request 
D_CONTROL call macro 



The next subroutine, HANDLER, is the attention event handler. It reads 
the attention character (CONTROL-Q) from .CONSOLE, then beeps 
thrice. If the previous character was ESCAPE, the program terminates. 
A buffer separate from the main I/O buffer is used for reading the attention 
character, as otherwise the attention character would sometimes clobber 
the character in the buffer before it could be written to the screen. 



The buffer BELLS contains three BEL characters, separated by a number 
of SYNC characters. When written to the console, these cause a total 
delay of about 150 ms. HBLK1 and HBLK2 are required parameter lists 
for the READ and WRITE calls. HBUF1 is a one-byte buffer for the 
attention character. 
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BELLS 


.EQU 




Buffer with BELs and delay: 




.BYTE 


07 


RPI 




.BYTE 


1 6, 1 b, 1 D, 1 D,l b, 1 b, 1 D, 1 D, 1 D 


OTINOS 




.BYTE 


07 






.BYTE 


ID, ib,ib, lb, ib.lb, ID, ib.lb 


QVMr^e 
O T NOS 




.BYTE 


07 


BEL 


BELLEN 


.EQU 


•-BELLS 


Calculate buffer length 


HBLK1 


.BYTE 


04 


4 required parameters for READ 


HREF1 


.BYTE 


00 


ref_num 




.WORD 


HBUF1 


data_buffer pointer 




.WORD 


0001 


request_count 




WDRD 

. VV WiU 


0000 


transfer count 


HBUF1 


.BYTE 





Buffer for reading attention char 


HBLK2 


.BYTE 


03 


3 required parameters for WRITE 


HREF2 


.BYTE 


00 


ref_num 




.WORD 


BELLS 


data_buffer pointer 




.WORD 


BELLEN 


request_count 


HBLK3 


.BYTE 


01 


1 required parameter for CLOSE 




.BYTE 


00 


; ref_num = 0: CLOSE all files 


HBLK4 


.BYTE 


00 


; required parms for TERMINATE 



These data structures are followed by the actual code of the event 
handler. Here the SOS calls are coded using macros. 

HANDLER 



LDA 


REF 


; Set up reference numbers 


STA 


HREF1 


; for console READ 


STA 


HREF2 


; and console WRITE 


SOS 


READ, HBLK1 


; Read attention character 


SOS 


WRITE, HBLK2 


; Write three BELs to .CONSOLE 


LDA 


BUFFER 




CMP 


#1B 


; IF last keystroke was ESCAPE 


BNE 


$010 




SOS 


0CC, HBLK3 


; THEN CLOSE all files 


SOS 


065, HBLK4 


; and TERMINATE 



$010 



JSR 
RTS 



ARMCTRLQ 



ELSE re-arm attention event 
and resume execution 
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The TERMINATE call could have been coded in the following 
perverse way: 

TERM BRK ; Begin SOS call 

.BYTE 065 ; calLnum for TERMINATE 

.WORD TERM ; parameter_list pointer 

Since the TERMINATE call has no parameters, the required parameter list 
need be only an ASCII null ($00). Thus TERM, the parameter_list pointer, 
points to the BRK that begins the call. 

A simpler coding, using a macro, is this: 

TERM SOS 065, TERM ; Pointer to BRK 

The following pages contain a complete listing of the program, including 
all subroutines and parameter lists, as well as the code necessary to 
generate a valid header 



7.2. 7 Complete Sample Listing 



PAGE - 

Current memory available: 17406 

0000 .ABSOLUTE 

0000 .NOPATCHLISI 

0000 .NOMACROLIST 

2 blocks for procedure code 16136 words left 
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0000 I 

Current memory available: 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 

0000 



.PROG SCREENWRITER 

16881 

**************************************************************** 

Screenwriter Program 

Sample Interpreter for SOS Reference Manual 
Don Reed and Thomas Root, U August 1982 



This program reads bytes from the keyboard, then writes 
them out to the screen, without filtering out control 
characters. It writes explicitly, without using screen 
echo. 

The interpreter contains an event mechanism. When 
CONTROL-Q is read, the console driver detects it as an 
event. The event is processed when control next returns 
to the interpreter. If the character typed before the 
CONTROL-Q is ESC, the event handler beeps thrice and 
issues a TERMINATE call; if not, the event handler just 
beeps thrice. 



Note on programming style: the style of this program is 
deliberately inconsistent, to show several ways to code 
SOS calls. They can be coded in line; they can be coded 
as subroutines. They can be coded with or without a 
macro, SOS. The macro itself can use the SOS call number, 
or it can use the name, via an .EQUate. In general, 
data structures appear before the code using them: this 
is recommended practice with the Apple III Pascal 
Assembler. 



The source file for the Screenwriter program is replicated 
as SCREENWRIT.TEXT on the ExerSOS disk. 



***************************************************************** 
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0000 




.PAGE 






0000 




. ***************************************************************** 


0000 










0000 




; Header 


Part of File 




0000 
0000 
0000 


















0000 


9000 


START .EQU 


9000 


; Code begins at $9000 


0000 




.ORG 


START- OE 


; Leave 12 bytes for header 


8FF2 










8FF2 


53 4F 53 20 4E 54 52 


.ASCII 


"SOS NTRP" 


; label for SOS.INTERP 


8FF9 


50 








8FFA 


0000 


.WORD 


0000 


; opt header length = 


8FFC 


0090 


.WORD 


START 


; loading address 


8FFE 


**** 


.WORD 


CODELEN 


; code length 


9000 










9000 


4C **** 


JMP 


BEGIN 


; Jump to beginning of code 


9003 










9003 




■ ****************************** 


*********************************** 
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3 SCREENWR FILE: 



4 SCREENWR FILE: 



9003 






.PAGE 


9003 






.PAGE 










9003 




• ***** 


************************************************************ 


9003 
















9003 








9003 
















9003 






Macros, Equates, and Global Data Area 


9003 






These v 


ariables are 


used 


for 


communication between the 


9003 








9003 






main program and the 


OPENCONS subroutine. 


9003 






The syntax for a SOS call using the macro below is 


















9003 








9003 
















9003 






SOS call num, parameter list pointer 


9003 
















9003 








9003 


08 


CNAME 


.BYTE 


08 




name length 


9003 






The macro definition for a SOS call block using the above 




2E 43 4F 4E 53 4F 4C 




.ASCII 


".CONSOLE" 




pathname of console 


9003 






format is below: 


900B 


45 














9003 




• 




900C 


00 


REF 


.BYTE 


00 




Console ref num 


9003 








900D 


00 


CONSNUM 


.BYTE 


00 




Console dev num 


9003 








900E 
















9003 






.MACRO SOS ; Macro def for SOS call block 


900E 

















9003 






BRK ; Begin SOS call block 






' 












9003 






.BYTE %1 ; call num 


900E 






Here is 


the data buffer for 


the READ and WRITE calls in 


9003 






.WORD %2 ; parameter list pointer 


900E 




! 


the main program. Only the 


first byte is written into; 


9003 






.ENDM ; end of macro definition 


900E 






one or 


both are written out. 




9003 












* 












9003 








900E 




































9003 








900E 
















9003 






Here are .EQUates for call nums: 


900E 


00 OA 


BUFFER 


.BYTE 


00, OA 




data buffer with trailing I.F 


9003 








9010 
















9003 
























9003 








90 10 
9010 
















9003 


OOCA 


READ 


.EQU OCA ; call num for READ 


901 






Here are required parameter 


lists for SOS calls in the 


9003 


OOCB 


WRITE 


.EQU OCB ; call""num for WRITE 


9010 






main program. 








9003 


0083 


D CNTL 


,EQU 083 ; call~num for D CONTROL 


9010 




I 












9003 








90 10 
















9003 








9010 
















9003 








9010 


01 


FENLIST 


.BYTE 


01 




1 


parameter tor SET FENCE 


9003 






Here are more .EQUates: 


9011 


00 




.BYTE 


00 






fence = 


9003 








9012 
















9003 








9012 


04 


RCLIST 


.BYTE 


04 




4 


parameters for READ 


9003 








9013 


00 


RREF 


.BYTE 


00 






ref num 


9003 


0000 


■ ■ : ■ 


.EQU 00 


9014 


0E90 




.WORD 


BUFFER 






data buffer pointer 


9003 


0080 


TRUE 


.EQU 80 


9016 


0100 




.WORD 


0001 






request count 


9003 








9018 


0000 


RCNT 


.WORD 


0000 






transfer count 


9003 


FFEF 


BREG 


.EQU OFFEF ; Bank register 


90 lA 
























901A 


03 


WPLIST 


.BYTE 


03 




3 


parameters for WRITE 










901B 


00 


WREF 


.BYTE 


00 






ref num (from OPEN call) 










901C 


0E90 




.WORD 


BUFFER 






data buffer pointer 










90 IE 


0000 


WONT 


.WORD 


0000 






request count 










9020 
























9020 




■ ************** 


************* 


**** 
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9020 






• PAGE 






9020 






. ******************************* 


********************************** 


9020 












9020 






; Main Program Code 




9020 












9020 












9020 












9020 






; This is 


the setup portion, executed at the start. 


9020 












9020 
9020 






















9020 


9020 


BEGIN .EQU 






9020 


20 


**** 


JSR 


OPENCONS 


Open .CONSOLE 


9023 


20 


**** 


JSR 


GETDNUM 


Get dev num 


9026 


20 


**** 


JSR 


SETCONS 


Disable echo 


9029 


20 


**** 


JSR 


ARMCTRLQ 


Arm attention event 


902C 






SOS 


60, FENLIST 


Set event fence to 0: 


9030 










here we coded "60" directly 


9030 












9030 


AD 


0C90 


LDA 


REF 


Set up ref num 


9033 


8D 


1390 


STA 


RREF 


for reads 


9036 


8D 


1B90 


STA 


WREF 


and writes 


9039 












9039 
9039 






















9039 






; This is 


the main loop, executed until termination. 


9039 












9039 












9039 












9039 






$010 SOS 


READ, RCLIST 


Read in one byte: 


903D 










here we used READ for OCA 


903D 


AD 


1890 


LDA 


RCNT 


IF nu bytes were read 


9040 


F0F7 


BEQ 


$010 


THEN go read again 


9042 










9042 


8D 


1E90 


STA 


WCNT 


Set up write count 


9045 


AD 


0E90 


LDA 


BUFFER 




9048 


C9 


OD 


CMP 


*0D 


IF first byte in buffer is CR 


904A 


DO** 


BNE 


$020 


THEN write out LF also 


904C 


EE 


1E90 


INC 


WCNT 




904F 












904F 






$020 SOS 


WRITE, WPLIST 


Write out I or 2 bytes 


9053 










9053 


4C 


3990 


JMP 


$010 


Repeat ad infinitum 


9056 












9056 






•**************^ 


************************************* *********,t J, 
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PAGE 


6 SCREENWR 


FILE: 






9056 




.PAGE 






9056 




-**************************************************************** 


9056 










9056 




; SUBROUTINES 




9056 
9056 










9056 










9056 




; OPENCONS: open the .CONSOLE file for reading 


9056 










9056 










9056 










9056 


04 


COLIST .BYTE 


04 


4 required parameters for OPEN 


9057 


0390 


.WORD 


CNAME 


pathname pointer 


905 9 


00 


CREF .BYTE 


00 


ref num returned here 


90 5A 


**** 


.WORD 


COPLIST 


option list pointer 


905C 


01 


.BYTE 


01 


length of opt parm list 


905D 










90 5D 


03 


COPLIST .BYTE 


03 


Open for reading and writing 


905E 










905E 










905E 




OPENCONS 




Here we didn't use a macro. 


90 5E 


00 


BRK 




Begin SOS call block. 


905F 


08 


.BYTE 


0C8 


Open the console. 


9060 


5690 


.WORD 


COLIST 


Pointer to parameter list 


9062 


AD 5990 


LDA 


CREF 


Save the result ref num 


9065 


8D 0C90 


STA 


REF 


for READS and WRITES. 


9068 


60 


RTS 






9069 










9069 


















9069 










9069 




; GETDNUM: Get the device number of .CONSOLE 


9069 










9069 










9069 










9069 


02 


GDLIST .BYTE 


02 


2 parameters for GET DEV NUM 


906A 


0390 


.WORD 


CNAME 


dev name pointer 


906C 


00 


GDNUM .BYTE 


00 


dev num goes here 


906D 










906D 










906D 




GETDNUM 






906D 


00 


BRK 






90 6E 


84 


.BYTE 


84 


Call GET DEV NUM 


906F 


6990 


.WORD 


GDLIST 




9071 


AD 6090 


LDA 


GDNUM 


Save the result dev num 


9074 


8D 0D90 


STA 


CONS NUM 


for console control 


9077 


60 


RTS 
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9078 
9078 






.PAGE 




















9078 




; 










9078 




; 


SETCONS: set the .CONSOLE file to suppress screen echo 


9078 




; 










9078 














9078 














9078 


03 


SETLIST 


.BYTE 


03 




3 required parms for D CONTROL 


9079 


00 


CNUM 


.BYTE 


00 




dev num of .CONSOLE 


907A 


OB 




.BYTE 


OB 




conTrol code = OB: screen echo 


907B 


**** 




.WORD 


CONLIST 




control~llst pointer 


907D 














907D 


00 


CONLIST 


.BYTE 


FALSE 




Disable screen echo 


907E 














907E 














907E 




SETCONS 










907E 


AD 0D90 




LDA 


CONSNUM 




Set up device number 


9081 


8D 7990 




STA 


cmjM 




of .CONSOLE 


9084 






SOS 


D CNTL, 


SETLIST 




9088 


60 




RTS 








9089 
9089 


























9089 














9089 






ARMCTRLQ: Am 


the Attention Event for CONTROL-Q 


9089 
9089 
9089 


























9089 


03 


DCLIST 


.BYTE 


03 




3 required parms for D CONTROL 


908A 


00 


DNUM 


.BYTE 


00 




dev num of .CONSOLE "goes here 


908B 


06 




.BYTE 


06 




control code" 06: 


90 8C 












Arm Attention Event 


90 8C 


**** 




.HORD 


CLIST 




control list pointer 


908E 














908E 




CLIST 








Control list 


908E 


FF 




.BYTE 


OFF 




Event priority 


908F 


02 




.BYTE 


02 




Event ID 


9090 


**** 




.WORD 


HANDLER 




Event handler address 


9092 


00 


BANK 


.BYTE 


00 




Event handler bank 


9093 


u 




.BYTE 


11 




Attention char = CTRL-Q 


9094 














9094 














9094 




ARMCTRLQ 








9094 


AD EFFF 




LDA 


BREG 




Set up bank number 


9097 


8D 9290 




STA 


BANK 




of event handler 


90 9A 


AD 0D90 




LDA 


CONSNUM 




Set up device number 


90 9D 


8D 8A90 




STA 


DNOM 




for control request 


90A0 






SOS 


D CNTL, 


DCLIST 


D CONTROL call macro 


90A4 


60 




RTS 
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90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A5 
90A6 
90AD 
90AF 
90B0 
90B7 
90 B9 
90BA 
90 BA 
90 BA 
90BB 
90 BC 
90BE 
9OC0 
90C2 
90C2 
90C3 
90C3 
90C4 
90C5 
90C7 
90C9 
90C9 
90CA 
90CB 
90CB 



HANDLER: Attention event handler subroutine 

This subroutine reads the attention character (CONTROL-Q) 
from .CONSOLE, then beeps thrice. If the previous 
character was ESCAPE, the program terminates. 

A buffer separate from the main data buffer is used for 
reading the attention character, as otherwise the 
attention character would sometimes clobber the character 
in the data buffer before it could be written. 

The buffer BELLS contains three BEL characters, separated 
by a number of SYNC characters. When written to the 
console, these cause a total delay of about 150 ras. 



90A5 












BELLS 


.EQU 


* 






; Buffer with BELs and delay; 


07 














.BYTE 


07 






; BEL 


16 16 


16 


16 


16 


16 


16 




.BYTE 


16, 16, 


16, 


16, 


16, 16, 16, 16, 16 ; SYNCs 


16 16 
07 














.BYTE 


07 






; BEL 


16 16 


16 


16 


16 


16 


16 




.BYTE 


16, 16, 


16, 


16, 


16, 16, 16, 16, 16 ; SYNCs 


16 16 
























07 














.BYTE 


07 






1 BEL 


0015 












BELLEN 


.EQU 


*-BELLS 






; Calculate buffer length 


04 












HBLKl 


.BYTE 


04 






; 4 required parameters for READ 


00 












HREFl 


.BYTE 


00 






; ref num 


**** 














.WORD 


HBUFl 






; data buffer pointer 


0100 














.WORD 


0001 






; request count 


0000 














.WORD 


0000 






; transfer count 


00 












HBDFl 


.BYTE 









; Buffer for attention character 


03 












HBLK2 


.BYTE 


03 






; 3 required parameters for WRITE 


00 












HREF 2 


.BYTE 


00 






; ref num 


A590 














.WORD 


BELLS 






; data buffer pointer 


1500 














.WORD 


BELLEN 






; request count 


01 












HBLK3 


.BYTE 


01 






; 1 required parameter for CLOSE 


00 














.BYTE 


00 






; ref num - 0: CLOSE all files 


00 












HBLK4 


.BYTE 


00 






; required parms for TERMINATE 
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90CC 
90CC 
90CC 
90CF 
90D2 
90D5 
90D5 
90D9 
90D9 
90DD 
90DD 
90EO 
90E2 
90E4 
90E4 
90E8 
90EC 
90EC 
90EF 
90F0 
90F0 
90F0 
90F0 
90F0 
90F0 
90F0 
90F0 
90F0 
90F0 
90F0 



AD 0C9O 
8D BB90 
8D C490 



AD 0E90 
C9 IB 
DO** 



20 9490 
60 



LDA 
STA 
STA 

SOS 

SOS 

LDA 
CMP 
BNE 

SOS 
SOS 

JSR 
RTS 



REF 
HREFl 
HREF 2 

READ, HBLKi 

WRITE, HBLK2 

BUFFER 

#1B 

SOlO 

OCC, HBLK3 
065, HBLK4 



Set up reference numbers 
for console READ 
and console WRITE 

; Read attention character 

; Write three BELs to .CONSOLE 

; IF last keystroke was ESCAPE 



THEN CLOSE all files 
and TERMINATE 



ELSE re-arm attention event 
and resume execution 



. ****************************************************** 
******************************************* 



****************** 



End of program — calculate length 



CODELEN .EQU *-START 
.END 



Calculate number of bytes in 
program 
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AB - Absolu 


te 


LB - Label 


UD 


- Undef ined 


MC 


- Macro 






RF - Ref 






DF - Def 




PR 


— Proc 




FC 


- Func 






PB - Public 




PV - Private 


CS 


— Const s 












ARMCTRLQ 


LB 


9094 


BANK 


LB 


9092 


BEGIN 


LB 


9020 


BELLE N 


AB 


0015 


CLIST 


LB 


908E 


CNAME 


LB 


9003 


CNUM 


LB 


9079 


CODELEN 


LB 


OOFO 


COPLIST 


LB 


905D 


CREF 


LB 


9059 


DCLIST 


LB 


9089 


DCNTL 


AB 


0083 


GDLIST 


LB 


9069 


GDNUM 


LB 


906C 


GETDNUM 


LB 


906D 


HANDLER 


LB 


90CC 


HBLK4 


LB 


90CB 


HBUFl 


LB 


90C2 


HREFl 


LB 


90BB 


HREF 2 


LB 


90C4 


READ 


AB 


OOCA 


REF 


LB 


90 OC 


RREF 


LB 


9013 


SCREENWR 


PR 




START 


AB 


9000 


TRUE 


AB 


0080 


WCNT 


LB 


901E 


WPLIST 


LB 


901A 


BELLS 


LB 


90A5 


BREG 


AB 


FFEF 


BUFFER 


LB 


900E 








COLIST 


LB 


9056 


CONLIST 


LB 


907D 


CONSNUM 


LB 


900D 








DNUM 


LB 


90 8A 


FALSE 


AB 


0000 


FENLIST 


LB 


9010 








HBLKI 


LB 


90BA 


HBLK2 


LB 


90C3 


HBLK3 


LB 


90C9 








OPENCONS 


LB 


905E 


RCLIST 


LB 


9012 


RCNT 


LB 


9018 








SETCONS 


LB 


907E 


SETLIST 


LB 


9078 


SOS 


MC 










WREF 


LB 


901B 


WRITE 


AB 


OOCB 
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Current minimum space is 15687 words. 

Assembly complete: 394 lines 

Errors flagged on this Assembly 
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7.3 Creating Interpreter Files 



The Apple III Pascal Assembler reads a source text file of assembly- 
language statements and creates a code file consisting of a header block, 
a code section, and a relocation section, if the code file is relocatable. A 
SOS interpreter file must be in a format different from the standard code 
file format that is used for a module: 

• It must be in absolute format, beginning at the proper memory location. 

• It must have a special header that identifies the file as an interpreter, 
and the standard header and trailer must be removed. 

• It must be named SOS.INTERP before it can be booted. 

A utility program, Makelnterp, transforms code files into 
interpreter files. Its use is described in Appendix C. 

7.4 Assembly-Language Modules 



An interpreter that is too large to fit into the the memory space allocated 
for it can be split up into a main interpreter and one or more assembly- 
language modules. An interpreter can also use modules if it is made to be 
extensible, or if it wishes to swap sections of machine code in and out of 
memory. A language interpreter may use modules to allow the user 
programs it interprets to call assembly-language subroutines. 

SOS does not directly support creating, loading, or maintaining modules: 
modules are defined, loaded, and called by the interpreter only. 

Whereas an interpreter must be written and assembled in absolute code, 
a module can be in either absolute or relocatable format. A stand-alone 
interpreter performing an application will probably only have to support 
absolute modules, if any. A language interpreter, however, may support 
relocatable modules, as do the BASIC and Pascal interpreters. 
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7.4. 1 Using Your Own Modules 



An interpreter can usetheREQUEST_SEG call to request a fixed memory 
segment in free memory, then load a 6502 code file into this space and 
execute its code. An interpreter can execute modules located in bank- 
switched memory by using the technique described in section 2.4.1 . 

In this way, an interpreter can have several sections of overlay code — 
subroutines that are swapped into a certain memory space only when 
they are needed, and are replaced by other code when their usefulness is 
expended. This is illustrated in Figure 7-2. 



module 



module 



free memory 



free memory 



driver 



driver 



SOS l<ernel 



driver 



interpreter 



SOS kernel 



\$2000 

\ last 
/ bank 

$A000 



$FFFF 



Figure 7-2. Interpreter and Modules 



Rather than allocating free memory, an interpreter can also overlay code 
into itself and execute it without bank-switching. This technique is 
dangerous unless you carefully control which parts of the interpreter are 
being overwritten. 
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7.4.2 BASIC and Pascal Modules 

The Apple Pascal and Business BASIC languages both have facilities for 
loading assembly-language modules or linking them with a Pascal or 
BASIC program. The modules are in the relocatable format produced by 
the Apple Pascal Assembler: the Pascal and BASIC interpreters are both 
designed to load, relocate, and execute files in this format. 

The BASIC and Pascal interpreters each place a module in a convenient 
place in memory, then use the relocation information in the code file to 
alter the program code to run in its new location. A BASIC program 
communicates with modules via PERFORM and EXFN statements; a 
Pascal program uses EXTERNAL PROCEDURE and FUNCTION calls. 
Whereas invokable modules used by BASIC are loaded dynamically at run 
time, modules used by Pascal are linked in with the Pascal host program 
during a post-compilation linking phase, and are stored as part of the final 
code file. 

Both the BASIC and Pascal interpreters pass parameters to their modules 
via the interpreter's stack. The modules remove and store the return 
information, then pull the parameter bytes off the stack and process them. 
When they are finished, they push the return information back on the 
stack and perform an RTS. 

A module used by the BASIC or Pascal interpreter does not need 
to know any entry points in the interpreter 

A module can access your programs or data by means of pointer 
parameters. The interpreter passes the two bytes of the pointer on the 
stack, and sets up the X-bytes of the pointer in a fixed location in the 
interpreter's X-page. The module pulls the pointer off the stack and stores 
its pointers in the proper places in the zero page: it can then use extended 
addressing to access the host program's data structures. 

You can find more information on the use of assembly-language modules 
with Pascal in the Apple III Pascal Program Preparation Tools manual, in 
the chapter The Assembler 
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7.4.3 Creating Modules 

Modules can be in either of two formats: absolute and relocatable. Tine 
absolute form is easier to load, but less versatile. If you can be sure a 
particular region of memory will be available for a module, you can 
assemble that module to fit into that region, and write a routine into your 
interpreter to load that module into that region. In doing so, you must take 
into consideration whether assembling a module to run in a particular 
region will affect the interpreter's memory requirements. You can also do 
this with a number of modules: you can even assemble several modules 
for the same region, if they are to be used one at a time and swapped in 
as needed. 

Relocatable modules can go anywhere in free memory, so they can more 
easily be used by machines of different memory sizes, driver sets, and so 
forth. A language interpreter that supports modules will probably support 
relocatable modules. However, such an interpreter must take care of the 
relocation itself. This task goes beyond the scope of this manual. The data 
formats of relocatable assembly-language code files are described in 
Appendix E; more detail is in the Apple III Pascal Technical Reference 
Manual. If you are designing an interpreter that supports relocatable 
modules and need further assistance, contact the Apple PCS Division 
Technical Support Department. 
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8. 1 Types of SOS Calls 



An interpreter communicates with SOS primarily through SOS calls. 
A SOS call is a request that SOS perform an action or return some 
information about a file, device, or memory segment. 

SOS calls fall into four categories: 

• File calls, which manipulate files according to the file model 
presented in Chapter 4; 

• Device calls, which manipulate devices according to the device 
model presented in Chapter 3; 

• Memory calls, which allocate and release memory for 
interpreters and keep track of areas of free memory; and 

• Utility calls, which access the system clock, the event fence, 
and other resources. 

The individual SOS calls are presented in Volume 2. The way a SOS call 
is made, however, is the same regardless of the function of the particular 
call; the remainder of this section discusses how an interpreter makes 
SOS calls. 

8.2 Form of a SOS Call 



A SOS call has three parts: the call block, the required parameter list, and 
the optional parameter list. Not every call has every part. The parts need 
not be in any particular order, and need not be contiguous, as they are 
linked by pointers. 

8.2.1 The Call Block 

A SOS call begins with the call block, a four-byte sequence executed as 
part of an interpreter's code. Figure 8-1 is a diagram of a call block, along 
with the code implementing it: 



■ 

I 
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54F9I00 CALBLK BRK 

54FA I C8 BYTE 0C8 ; OPEN 

54FB|2052 .WORD PLIST ; PTR 



$54F9 
$54FA 
$54FB 
$54FC 



$00 BRK 


$08 


call_num 




value 


$20 


parm_list 


$52 


pointer 



Figure 8-1. SOS Call Block 
The SOS call block has three fields: 
BRK (1 byte): 

This field always contains the BRK opcode, $00; 



call_num (1 byte): 

This field contains the SOS call number, which must correspond to a valid 
SOS call. 



parm_list (2 bytes): 

This field contains a pointer to the required parameter list for this SOS 
call. The parm_list is an address in S-bank notation, $nnnn, which specifies 
a location in the current bank or in the S-bank, never in the zero page. The 
location specified contains the first byte of the required parameter list for 
the call being made: the required parameter list is described below. 



If the call_num or the parm_list is invalid, SOS returns an error code to 
the caller. 



If the format of the SOS call is correct, SOS performs the requested 
action. After the call is completed, SOS restores the state of the machine 
(the values in the X- and Y-registers and all status flags except Z and N) 
and returns control to the caller. If an error was encountered, the error 
code is returned in the accumulator If the call was error-free, the 
accumulator returns $00. You can think of a SOS call as a 4-byte LDA 
#ERRORCODE instruction; you can check for the presence of an error 
code with the BEQ and BNE instructions. 
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8.2.2 The Required Parameter List 

The required parameter list is a table in memory that the interpreter uses 
to communicate with SOS. It is from here that a SOS call gets the 
information it needs, and it is also h6re that the call returns information 
to the caller 

Each SOS call expects a certain number of parameters: the number and 
type of parameters is different for each call. But the first byte of the 
required parameter list for any SOS call always contains the number of 
parameters for the call (not the number of bytes in the list). SOS checks 
this number against the number of parameters the call is expecting, to 
verify that you've supplied the correct list for that call. If the numbers don't 
match, SOS returns an error message. 



Figure 8-2 is a required parameter list: 



I 
I 
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54F9I00 CALBLK BRK 
54FA|C8 
54FB|2052 



BRK 
BYTE 


0C8 ; OPEN 


$54F9 


$00 BRK 


.WORD 


PLIST ; PTR 


$54FA 


$08 


call_num 

value 






$54FB 


$20 


pann_llst 






$54FC 


$52 


pointer 



5220104 PLIST .BYTE 

5221 10652 PATHN .WORD 

5223100 REFNUM .BYTE 

522410052 OPLIST WORD 

5226104 OPLEN .BYTE 



04 

FILE1 ; PTR $5220 
00 ; VALUE 
REQACO ; PTR $5221 
04 ; VALUE 

$5222 
$5223 
$5224 
$5225 
$5226 



$04 


parm count 

value 


$06 


pathname 


$052 


pointer 


$00 


ref_num 

result 


$00 optionjist 


$52 


pointer 


$04 


length 

value 



Figure 8-2. The Required Parameter List 



This list contains all the required parameters for the call. A value must be 
supplied for each parameter: no default values are assumed. The number 
of parameters and the length of the required parameter list are constant 
for any one SOS call, and usually different for every call. 



Parameters are of the four types listed below. 



• A value parameter is 1 , 2, or 4 data bytes passed from the caller to 
SOS. The caller places a value in the proper field of the parameter 
list, destroying its previous contents; SOS reads it without 
changing it. 

• A result parameter is 1 , 2, or 4 data bytes returned by SOS to the 
caller. SOS places a result in the proper field of the parameter list, 
destroying its previous contents; the caller reads the result 
without changing it. 
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• A value/result parameter is 1 , 2, or 4 data bytes that are read and 
modified by SOS: the value and the result share the same space. 
The caller places a value in the proper field of the parameter list, 
destroying its previous contents; SOS reads the value and 
replaces it with a result, destroying the value. Few parameters 
are of this type. 

• A pointer parameter is a 2-byte address (in any format— see 
section 8.3.1 below) that specifies the beginning of a buffer 
established by the caller SOS uses the pointer to read information 
from the buffer or to return data to the same buffer Pointers allow 
you to exchange variable-length data with SOS. Pointers are 
discussed in more detail in section 8.3. 

The calling program supplies a pointer to SOS: SOS never returns or 
alters a pointer It either reads from or writes to the buffer the pointer 
points to. 

Some required parameter lists can be used for more than one call, usually 
for a pair of complementary calls. In the case of GET_FILE_INFO and 
SET_FILE_INFO (which read and change miscellaneous information 
about a file), you can call the former, examine its results in the required 
parameter list, perhaps change them, and call the latter with the same 
required parameter list to make your changes take effect. 



8.2.3 The Optional Parameter List 

Some SOS calls have parameters that need not be supplied for their 
simplest operation. These parameters are stored in an optional parameter 
list. A pointer (option_list) in the required parameter list specifies the first 
byte in the optional parameter list, and a length parameter in the required 
parameter list indicates how many bytes of optional parameters are 
supplied. Figure 8-3 is an optional parameter list: 
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54F9I00 
54FA| C8 
54FBI2052 



5220104 
5221 10652 
5223100 
522410052 
5226104 



CALBLK BRK 
.BYTE 
.WORD 



PLIST 

PATHN 

REFNUM 

OPLIST 

OPLEN 



.BYTE 

.WORD 

.BYTE 

.WORD 

.BYTE 



008 ; OPEN 
PLIST ; PTR 



04 

FILE1 ; PTR 
00 ; VALUE 
REQACC ; P" 
04 ; VALUE 



5200103 


REQAOO 


.BYTE 


03 


VALUE 


5201 104 


PAGES 


.WORD 


04 


VALUE 


5202 0055 


lOBUF 


.WORD 


00 


PTR 



$54F9 


$00 BRK 


$54FA 


$08 


call num 

value 


$54FB 


$20 


parmjist 


$54FC 


$52 


pointer 








$5220 


$04 


parmcount 

value 


$5221 


$06 pathname 


$5222 


$52 


pointer 


$5223 


$00 

* result 


$5224 


$00 optionjist 


$5225 


$52 


pointer 


$5226 


$04 


length 

value 








$5200 


$03 


req_access 

value 


$5201 


$04 


pages 

value 


$5202 


$00 iobuffer 


$5203 


$55 


pointer 



Figure 8-3. Optional Parameter List 
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You can supply any number of optional parameters, depending upon 
what you want the call to do. If the length of the optional parameter list 
is $00, the call will expect no optional parameters. If the length is non- 
zero, the call will expect as many optional parameters as can fit in that 
number of bytes. 

Some calls supply default values for optional parameters that are not 
supplied; see the individual call description. 

8.3 Pointer Address Extension 



Some parameters in the parameter lists are pointers, which are simply 
addresses of other data structures (usually buffers) in memory. You can 
supply these addresses in S-bank, current-bank, indirect, or extended 
format, all of which are described in section 2.1 . 

When you make a SOS call involving a buffer, you must give a pointer 
to the buffer, and the number of bytes to be acted on. For example, the 
READ call requires a data_buffer pointer and a request_count parameter 
specifying how many bytes are to be read. SOS takes care of incrementing 
the pointer to read successive bytes: you need only tell it how to find the 
first byte. 

There are two kinds of pointers: 

• A direct pointer is a two-byte address in current-bank or S-bank 
format. This address is that of the beginning of the buffer in the 
current or S-bank. 

• A indirect pointer is a two-byte address whose high byte is $00. 
This address specifies a zero-page location: the location contains 
the indirect or extended address of the beginning of the buffer 

in memory. 

SOS converts both kinds of pointers into extended addresses. It does not 
change the pointers in your parameter list: instead it moves them to its 
own zero page so it can use them as extended addresses. The following 
paragraphs describe how SOS handles different kinds of pointers. 
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For all pointer conversions, SOS checks only that the pointer 
indicates a valid location: it does not ensure that the structure 
pointed to is in a valid place. It does not verify that the location 
pointed to actually exists in system RAM. There are limits on how 
big and where the buffer can be: such restrictions are discussed 
with each conversion. 



8.3.1 Direct Pointers 



A direct pointer can specify a location in either the S-bank or the current 
bank. If the latter, the current bank can be either bank or some other 
bank. These cases are considered here. 



Figure 8-4 shows a direct pointer: 



$62A4 
$62A5 



$41 


pointer 




low byte 


$71 


pointer 




high byte 







data 


$7141 
$7142 













Figure 8-4. A Direct Pointer 



8.3. 1. 1 Direct Pointers to S-Banf< Locations 

SOS moves the pointer directly to its zero page without conversion, and 
sets the X-byte of the pointer to $00 to form a normal indirect address. 

Original Pointer Extended Form 



$nnnn $A000 to $B7FF 



$00:nnnn $00: A000 to $00: B7FF 
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A buffer that begins in the S-bank must reside in a contiguous 
region of S-banl< memory. For example, if you start reading from 
a buffer beginning at location $A000 and read $200 bytes, you will 
cover the address range $A000 to $A1 FF. If you read beyond 
$B7FF you will run into SOS's region. 



8.3.1.2 Direct Pointers to Current Bank Locations 

SOS converts such pointers to extended form. If the current bank is not 
bank 0, SOS creates an X-byte based on the caller's current bank number, b. 
The result is converted to ensure that the resulting pointer specifies 
neither the zero page nor the last page of a bank pair 

Original Pointer (banl( <> 0) Extended Form 



$nnnn $2000 to $21 FF $xx:nnnn $8b-1 :8000 to $8b-1 :81 FF 

$nnnn $2200to$9FFF $xx:nnnn $8b:0200to $8b:7FFF 

If the current bank is bank 0, then the address is converted to an 
extended address v/hose X-byte is $8R 

Original Pointer (banl( = 0) Extended Form 



$0:nnnn $0:2000 to $0:9FFF $8F:nnnn $8F:2000 to $8F:9FFF 

A buffer that begins in switched memory must lie entirely within 
switched memory. If a buffer begins between $b:2000 and 
$b:9FFF, it can extend up to 64K bytes, and can wrap across 
bank boundaries, if b is not zero. For example, if you start reading 
from a buffer at $b:9F00 and read $200 bytes, you will cover the 
ranges $b:9F00 to $b:9FFF and $b+1 :2000 to $b+1 :20FF However, 
the buffer may not go into the address range $A000 to $FFFF 



8.3.2 Indirect Pointers 

I ndirect pointers are always stored on the caller's zero page. The two-byte 
value in the parameter list is the address of the pointer on zero page. 
When SOS processes an indirect pointer, it moves the two bytes of the 
pointer from the caller's zero page to its own zero page, and also moves 
the X-byte of that pointer to its own X-page. 



■ 
■ 
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An indirect pointer can have an X-byte equal or unequal to zero: if it is 
equal to zero, the bank number can likewise be equal or unequal to zero. 
These cases are considered here. 



Figure 8-5 shows an indirect pointer: 



$62A4 



$20 pointer 
low byte 



$00 pointer 
high byte 



$0020 






$41 pointer 


$0021 


low byte 




$71 pointer 




high byte 











data 


$81:7141 
$81:7142 

• 
• 
• 











$1620 
$1621 



$81 pointer 
X-byte 



Figure 8-5. An Indirect Pointer 



8.3.2. 1 Indirect Pointers with an X-Byte of $00 

These pointers are converted by SOS to full extended addresses, as in 
the direct-pointer examples above. An indirect pointer with an X-byte of 
00 is identical to a direct pointer and follows the cases shown above. 
SOS creates an X-byte based on the caller's current bank number, b. 
The address may be converted to prevent it from pointing to the zero 
page, as shown in the first line below. 

Original Pointer Extended Form 



$00:nnnn $00:$2000 to $00:$21 FF $xx:nnnn $8b-1 :8000 to $8b-1 :81 FF 
$00.-nnnn $00:$2200 to $00:$9FFF $xx:nnnn 8b:0200to $8b:7FFF 

If the current bank is bank 0, the address is converted to an extended 
address whose X-byte is $8F. 
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Original Pointer (banl( = 0) Extended Form 



$00:nnnn $00:2000 to $00:9FFF $8F:nnnn $8F:2000 to $8F:9FFF 

A buffer that begins in switched memory must lie entirely within 
switched memory. If a buffer begins between $b:2000 and 
$b:9FFF, it can extend up to 64K bytes, and can wrap across 
banl< boundaries, if b is not zero. For example, if you start reading 
from a buffer at $b:9F00 and read $200 bytes, you will cover the 
ranges $b:9F00 to $b:9FFF and $b+1 :2000 to $b+1 :20FF However, 
the buffer may not go Into the address range $A000 to $FFFF 



8.3.2.2 Indirect Pointers witli an X-Byte Between $80 and $8F 
These pointers are invalid if they point to the zero page or stack: 
Original Pointer Extended Form 



$80:nnnn $80:0000 to $80:01 FF Invalid 
$8x:nnnn $8b:0000 to $8b:00FF Invalid 

The range of addresses in the second line could be replaced by alternate 
form, $8b-1 :8000 to $8b-1 :80FR This trick doesn't work in the first case, 
as bank is the lowest bank. 

Indirect pointers that have an X-byte between $80 and $8E are converted 
only to ensure that addresses produced by indexing on them do not point 
to the zero page. The pointers below are converted: 

Original Pointer Extended Form 



$8x:nnnn $8b:01 00 to $80:01 FF $8x:nnnn $8b -1 :81 00 to $8b - 1 :81 FF 

%8x:nnnn $8b:FF00 to $80:FFFF $8x:nnnn $8b+1 :7F00 to $8b+1 :7FFF 

The pointers below are unchanged: 

Original Pointer Extended Form 



$8x:nnnn $8b:0200 to $8b:FEFF $8x:nnnn $8b:0200 to $8b:FEFF 
%8F:nnnn $8F:2000 to $8F:B7FF $8F:nnnn $8b:2000 to $8b:B7FF 



■ 

■ 
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The X-byte $8F is a special case that looks like a direct pointer if b is zero. 




The buffer that the above address points to can contain up to $FFFF 
bytes, and can wrap from one switched bank to another SOS will handle 



all the pointer manipulations automatically. A buffer cannot, however, 
cross over into S-bank space; and it must reside in no more than three 
adjacent banks. 



8.4 Name Parameters 



Many SOS calls use device names, volume names, or pathnames as 
parameters. Since a name is a variable-length string of characters, it 
cannot be included in a parameter list: you must supply a pointer to a 
name. The pointer can be specified in any of the formats described above. 
Figure 8-6 illustrates the format of a name parameter. 



$32A0 


$02 


$32A1 


$83 


dev_name 


$32A2 


$5A 


pointer 


$32A3 


dev num 

^ reiult 








$5AB3 


$03 


length 

value 


$5AB4 


$2E 


$5AB5 


$44 


'D' 


$5AB6 


$31 


'1' 



Figure 8-6. Format of a Name Parameter 
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The first byte pointed to by the parameter contains the number of 
characters in the rest of the name; the bytes immediately following 
contain the individual characters in sequence. 

Device and volume names can contain up to 15 characters: such names 
use 2 to 16 bytes of storage. Pathnames can be up to 255 characters in 
length: such names require 2 to 256 bytes of storage. 

8.5 SOS Call Error Reporting 



After execution of a SOS call, the accumulator contains the error code 
reported by the call, and the N and Z status flags are updated accordingly. 
All other registers are returned to their state before the call. If the call was 
completed successfully, the accumulator contains $00: a BEQ instruction 
can detect a successful SOS call. 

Error numbers range from $01 to $FF. Errors can be classified into groups 
by their error numbers: 

• Error codes $01 through $05 indicate a problem with the form of 
the SOS call, or its parameters or pointers. 

• Error codes $10 through $2F indicate device call errors. Either a 
requested operation is not supported by SOS, or the operation 
cannot be performed due to interface problems with a device. 
Some of these errors can also be produced by file calls. 

• Error codes $30 through $3F are generated by individual device 
drivers, and they indicate a problem in a particular device. 

• Error codes $40 through $5A indicate file call errors. 

• Error codes $70 through $7F indicate utility call errors. 

• Error codes $E0 through $EF indicate memory call errors. 

These errors can be generated by SOS for any SOS call: 
$01: Invalid SOS call number (BADSCNUM) 

The byte immediately following the BRK instruction ($00) in the SOS call 
block is not the number of a currently defined SOS call. 
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$02: Invalid caller zero page (BADCZPAGE) 

SOS requires that the interpreter use page $1 A as its zero page when 
calling SOS. 

$03: Invalid indirect pointer X-byte (BADXBYTE) 

The extension (X-) byte of an indirect pointer is invalid. Legal values for 
this byte are 

$00 Indirect, current bank 

$80 through $8E Indirect, extend bank 
$8F Indirect, S/0 bank 

$04: Invalid SOS call parameter count (BADSCPGNT) 

The first byte of the required parameter list contains a parameter count 
not expected by the specified SOS call. Either the call number is incorrect 
or the call is using the wrong required parameter list. 

$05: SOS call pointer out of bounds (BADSCBNDS) 

A SOS call pointer parameter is within a proscribed range of memory. 
Either the required parameter list resides on zero page or a pointer is 
attempting to point into SOS. The proscribed memory ranges are: 

$0100 through $01 FF Restricted for SOS 
$8800 through $FFFF Restricted for SOS 

$xx:0000 through $xx:00FF Zero Page 

$8F:0100 through $8F:01FF Restricted for SOS 
$8F:B800 through $8F:FFFF Restricted for SOS 
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data formats for relocatable 
146 

module 19,118,143-146 

linking 145 

loading 145 
procedure [136] 

attribute tables [136], [137] 
programming xvii 
asynchronous operations 5 

of device drivers 1 04 
attribute table [136], [138] 
assembly-language procedure 

[136] 



format of [137] 

procedure [136] 
.AUDIO [111] 
audio [111] 

aux_type 64, 88, [5] , [ 1 4] , [ 1 9] 
B 

B field 14 

backup bit 90, [12], [18] 
Backup III 90, [13] 
BADBKPG [88] 
BADBRK [127] 
BADBUFNUM [128] 
BADBUFSIZ [128] 
BADCHGMODE [88] 
BADCTL [71] 
BADCTLPARM [71] 
BADCZPAGE 161 
BADDNUM [71] 
BADINT [127] 
BADJMODE [104] 
BADLSTCNT [56] 
BADOP [72] 
BADPATH [53] 
BADPGCNT [88] 
BADREFNUM [54] 
BADREQCODE [71] 
BADSCBNDS 161 
BADSCNUM 160 
BADSCPCNT 161 
BADSEGNUM [88] 
BADSRCHMODE [88] 
BADSYSBUF [56] 
BADSYSCALL [127] 
BADXBYTE 161 
BCBERR [128] 
bank 

$0 16 

current 12 

highest 11 
switchable 15 
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number 15 

pair 13,14 
highest 15 

part of segment address 25 

register 11,19,28 
restoring contents of 31 

switchable 1 1 
bank-pair field 14 
bank-switched address 10, 12, 

30, 32 

as intermediate form 32 

notation 1 5 
bank-switched memory 

addressing 10-13,30-31 
bank-switched notation 23 
bank-switching 27, 28, 30 

for data access 30 

for module execution 30 

restrictions 28 
base 23, 1 22, [43] , [48] , [75] , [78] , 

[83] 
BASE 122 

base-relative relocation table 

[138] 
BASIC 118,143 

and Pascal modules 145 

interpreter 145 

program 145 
BCS [139] 
bibliography [141] 
bit 

backup 90, [12], [18] 
destroy-enable [12], [18] 
enhanced-addressing 14 
map 54 

read-enable [12], [18] 
rename-enable [12], [18] 
write-enable [12], [18] 

bit map pointer 82 

BITMAPADR [56] 

.BLOCK [139] 



block(s) 77 

addresses of 96, 97 
allocation 

for sparse files 98 

scheme 95 
altering configuration 46 
call 148-149, [x] 
configuration 43 

altering 46 
data 93, 96 
device 8, 40, 76 

logical 53 

status request $00 [60] 
device information (DIB) 43 
DIB configuration 43 
file 50-56,62 
control 64 
structure of 50-51 
index 93, 94 
key 77, 82, 93, 97 
logical 77 

master index 94, 96, 97 

maximum index 94 

on a volume 77 

SOS call [103] 

subindex 94, 96 

total 45, 82 
blocl(s used 63,87, [19] 
BNE ]l39] 
bootstrap 

errors [128] 

loader 77, 93 
BRK 149 

instruction 8 
BTSERR [55] 
buffer 

data 50, [117] 
editing [117] 

I/O 50 

space, for drivers 21 
string [117], [118] 
BUFTBLFULL [56] 
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.BYTE [139] 
byte 99, [133] 

extension 14, 31 (See also 

X-byte) 
locating in a standard 

file 98-99 
numbering 51 
order of pointers 79 
position, logical 98 

C 

call(s) 

block 148-149, [x] 

SOS [103] 
choosing [114] 
coding TERMINATE 131 
D_CONTROL 128 
device 46-47, [58-71 ] 

errors [71-72] 

management 5 
errors 

device 160, [71-72], [125] 

file 160, [53-56], [125-126] 

memory 160, [88] 

utility 160, [104], [126] 
file 69-73, [2-53] 

errors [53-56] 

management 5 
FIND_SEG 30 
form of the SOS 160 
memory 25-27, [74-87] 
errors [88] 
management 5 
OPEN 128 
REQUEST_SEG 30 
SOS 8 

error reporting 160 

form of a 148-154 

types of 148 
utility [90-103] 

errors [104] 

management 5 
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capacity of a file, maximum 94 
carry 15 
CFCBFULL [53] 
changing device 
name 46 
subtype 46 
type 46 
changing slot number 46 
change mode [81] 
CHANGE_SEG 26, [81-82] 
character 
device 8, 40 
control code $01 [64] 
control code $02 [64] 
status request $01 [60] 
status request $02 [61 ] 
file(s) 50-56, 57 

structure of 50-51 
line-termination 67 
newline 67 
null (ASCII $00) 97 
streams 40 
termination 67 
circumvention of programming 

restrictions 3 
clock 112-113, [95], [97], [98] 
rate 19 
system 112 
CLOSE 66, 68, 72, 90, [39-40] 
closed files 52-53 
closing files before TERMINATE 

[103] 
CMP 31 
code 

file(s) 145 
data formats of relocatable 
assembly-language 146 
organization [132] 
assembly-language [131-139] 
code part of [135] 
fragments, examples xiv 
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interpreter, executing 10 

part of a code file 119,121, 
[132], [135] 

segments, executing 27 

sharing 44 

procedure [136] 
code length 120 
CODEADDR [134] 
CODELENG [134] 
colon 15 

command interpreter [103] 
common code 44 
common file structure 3 
common foundation for 

software 3 

defined 2 
communicating with the 

device 42 
comparing two pointers 37-38 
compatibility with future 

versions 18 
conditions for enhanced indirect 

addressing 31 
configuration block 43 

alter 46 

DIB 43 
conflicts 

between interrupts 104 

with zero page 16 
.CONSOLE 66, 1 05, 1 08, 1 25, 

[109] 
console 40 

constant, relocation [138] 
control 

block, file 64 

flow of 27 

transfer 28 
CONTROL-C [117] 
CONTROL-RESET [117] 
controlcode [63] 

$01 , character device [64] 

$02, character device [64] 
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conversions 32 
copy-protection [103] 
copying sparse files 98 
CPTERR [55] 
CPU 104 

CREATE 68, 69, 90, 98, [3-6] 
creating interpreter files 1 43 
creation date and time 64, 81 , 84, 

88, 89-90 

field 89-90 
current 

bank 12 

direct pointers to 156 

directory 62 

position marker 51 
current-bank 

address 12,38 

form 13 
cylinders 77 

D 

.D1 [109] 
.D2 [109] 
.D3 [109] 
.D4 [109] 

D_CONTROL 45, 47, 1 08, 1 25, 

128, [63-64], [118] 
D_INFO 43,45,47, [67-71] 
D_STATUS 45, 46, [59-61 ], [118] 
data 

access 10,27,29-32 
bank-switching for 30 

and buffer storage 1 9 

block 93,95,96 

buffer 50, [117] 
editing [117] 

formats of relocatable 
assembly-language code 
files 146 

in free memory 30 
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data block 99 
data^buffer [35], [37] 
date and time 

creation 64, 81 , 84, 88, 89-90 

format 90 

last mod 64,88,89-90, [14], 
[19] 

decimal numbers xix 
decimal point xix 
DESTROY 68,69, [7-8] 
destroy-enable bit [12], [18] 
detecting an event 105 
dev name 43, 60, [23], [65], [67] 
dev~num 43, [59] , [63] , [65] , [67] 
devjype 44, 45, [68] 
devrce(s) 8, 40-42 

adding a 46 

block 8,40 

call(s) 46-47 
errors 160, [125] 

changing name of 46 

character 8, 40 

communicating with the 42 

control information 45 

correspondence 
logical/physical 54 
special cases of 54 

defined as logical device 54 

driver(s) 5,41,77,104,107, 
108, 125 

asynchronous operation of 
104 

environment 20-21 
errors, individual 160 
graphics 16 
standard [109-111] 
memory placement 21 

independence 7, 67 

information 43-44 
block (DIB) 43 

input 40 
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block 53 
management calls 5 
multiple logical 54 
name(s) 41 -42, 44, 50, 55, 60 

illegal 42 

legal 42 

syntax 42 
number 44 
operations on 45-46 
output 40 
peripheral 8,104 
physical 40 
random-access 7 
removing a 46 
requests 50 
sequential-access 7 
status information 45 
subtype 44 

changing 46 
type 44 

changing 46 
device-independent I/O 67 
DIB 

configuration block 43 

header 43 
dictionary 8 

current 62 

entry 62 
procedure [135], [136] 

error (DIRERR) [55] 

file 57-58 
format(s) 78-92 

header 78 
storage formats 76 

segment [132], [134] 

volume 54, 57, 78 
digit(s) 42, 56 

hexadecimal 12 
direct pointer 154,155 

to S-bank locations 155 
directory file, reading a 91-92 
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DIRERR [55] 
DIRFULL [55] 
disarming events 108 
Disk III driver 41 
disk drives 40 
disk, flexible 42,77,93 
DISKSW [72] 
dispatching routine 28 
displacement [43], [48] 
Display/Edit function [117] 
DNFERR [71] 
dollar signs xviii,xix 
driver 

device See device driver 
module 41 

placement of 44 
DRIVER FILE NOT FOUND [129] 
DRIVER FILE TOO LARGE [129] 
DUPERR [54] 
DUPVOL [56] 

E 

E-bit 14 

editing data buffer [117] 
EMPTY DRIVER FILE [129] 
empty file 65 

end-of-file marker See EOF 
enhanced 

addressing bit 14 

addressing modes 8 

indirect addressing 10,13-16, 
27,30, 31-32 
conditions for 31 
ENTER 10 [138] 
entries per block 82, 85, 92 
entry (entries) 86 

active 86 

directory 62 

FOB 53,62 

format compatibility 91 

inactive 86 
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storage formats of 76 
entryjength 81 , 84, 92 

environment 

attributes 19 

execution 16-22 

interpreter 18-19 

SOS device driver 20-21 

SOS Kernel 19-20 

summary 22 
EOF 51 , 53, 63, 64-65, 68, 87, 89, 

94, 95,96, 97,98, [5], [19], [49] 

limit 94 

movement of 
automatic 65 
manual 65-66 

updating 65 
EOFERR [55] 
EOR 31 
error(s) [124] 

bootstrap [128] 

device call [125] 

file call [125] 

messages [123-130] 

numbers range 160 

reporting, SOS call 160 

SOS 
fatal [124], [126] 
general [124] 
non-fatal [124] 

utility call [126] 
event(s) 5,104-115 

any-key 105 

arming, example 129 

arming and response 1 05, 1 08, 
125 

attention 105 
detecting an 105 
disarming 108 
existing 108 
fence 106,109-110 
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handler(s) 5,107,110-111,125 

address of 108 

examples 129 
handling 106,107 

system status during 1 1 1 
identifier (ID) 108 
mechanism, sample 1 26, 1 29, 

139 

priority 105,108 

processing 106 

queue 106,108-109 
order 109 
overflow [127] 

summary of 112 
EVQOVFL [127] 
examples 

code fragments xviii 

sample programs xviii 
executing 

code segments 27 

interpreter code 10 
execution 

environment 16-22 

speed 19 
ExerSOS [113-119] 
EXFN 145 

extended to bank-switched 
address conversion 34-35 
extension byte 14,31 (See also 
X-byte) 

extension, pointer address 154 
EXTERNAL PROCEDURE 145 
eye symbol xv 

F 

FOB 52 

entry 53, 62 
FCBERR [128] 
FCBFULL [54] 
fence [91], [93] 
fence, event 106, [91], [93] 



field(s) 

formats 89-92 
bank-pair 14 
pointer 79 
FIFO (first-in, first-out) 109 
FILBUSY [55] 
file(s) 7-8, 52 

assembly-language code [133] 
block 50-56, 62 

allocation for sparse 98 
call(s) 69-73, [2] 

errors 160, [125] 
character 50-56, 57 
closed 52-53 
closing before TERMINATE 

[103] 
code 145 

part of a code [135] 
control block 64 
copying sparse 98 
creating interpreter 143 
data formats of relocatable 
assembly-language code 
146 
defined 50 
directory 57-58 
format 78-92 
relocatable 120 
or absolute 143 
reading 91-92 
empty 65 

entry (entries) 78, 85-89 

inactive 86, 89 

sapling 89 

seedling 89 

subdirectory 89 

tree 89 
information 62-64 
input/output 67 
interpreter, creating an 1 43 
level, system 66 
management calls 5 
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name(s) 58-59, 60 

illegal 59 

legal 59 

syntax 59 
open 52-53, 63 
operations on 68 
organization 76-99 

code [132] 
sapling 93, 95 
seedling 93, 95 
SOS 56-62 
sparse 63, 94, 97-98 
standard 57-58 

locating a byte in 98-99 

sto rage f o rmats of 92-99 
structure 

common 3 

hierarchical 8 

of a block 50-51 

of a character 50-51 

of a sapling 96 

of a seedling 95 

of a tree 96 
subdirectory 57, 78 
system 

relationship to device 
system 57 

root of 59 

SOS 55-62 

tree 61 
top-level 57 
tree 94,96-97 

growing a 92-95 
type 68 

volume directory 77 
file count 82, 85 
file name 60,63,80,83,87 
file'type 64, 87, 91, [4], [13], [18] 
FIND_SEG 26, 30, 1 21 , 1 22, 

[77-79] 

flexible disk 42, 77, 93, [109] 



floppy disk See flexible disk 

flow of control 27 

FLUSH 66,72, [37], [41-42] 

FNFERR [54] 

form 

bank-switched 13 

current-bank-switched 13 

of a SOS call 148,160 
format(s) 

absolute or relocatable 143 

date and time 90 

directory file 78 

of attribute table [137] 

of directory files 78 

of information on a volume 77 

of name parameter 1 59 

of relocatable assembly- 
language code files, data 146 

relocatable 120 

volume 77 
free memory 23 

data in 30 

obtaining 121-124 

segment allocated from 29 
free blocks [23] 
.FUNG [136], [139] 
FUNCTION 145 
future versions 

compatibility with 18 

of SOS 91,92,93 

G 

general purpose communications 

(.RS232) [111] 
GET_ANALOG 113,115, 

[99-101] 

GET_DEV_NUM 43, 44, 45, 47, 
[65] 

GET_EOF 65, 66, 68, 73, [49] 
GET_FENCE 110, 114, [93] 
GET_FILE_INFO 63,65,68,70, 
152, [17-21] 
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GET_MARK 66, 68, 72, [45] 
GET_PREFIX 70, [27] 
GET_SEG_INFO 26, [83-84] 
GET_SEG_NUM 26, [85] 
GET_TIME 90, 112, 115, [97-98] 
.GRAFIX [110] 
graphics 16, [110] 
area 16 

device drivers 16 
growing a tree file 92 

H 

hand symbol xv 
handler 

event 5,125 

interrupt 5 
handling an event 106, 107 
hardware 8,10 

independence 2 

interrupt 105 
header(s) 43,119 

directory 78, 79-82 

subdirectory 82-85, 89 

volume directory 79, 80, 89 
header pointer 89 
heads 77 

hexadecimal (hex) xviii 

digit 12 

numbers xviii 
hierarchical file structure 8 
hierarchical tree structure 56, 76 
high-order nibble [117] 
highest bank 11 

pair 15 
highest switchable bank 15, 18 
highest-numbered bank 23 
housekeeping functions 3 
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block 51 
buffer 50,127 
character 51 
device-independent 67 
ERROR [129] 
implementation versus interface 
76 

warning 99 
INCOMPATIBLE INTERPRETER 
[129] 

increment loop 124 

one-bank example of 124 
incrementing a pointer 36-37 
index block(s) 93, 94, 95 
master 94 
maximum 94 
sub- 94, 96 
index_block 99 
indexed mode, zero-page 29 
indexing 15 

addresses 15 
indirect 

addressing 10 
enhanced 10, 13-16, 27, 30, 

31-32 
normal 14 
operation, normal 31 
pointer(s) 154,156,157 
with an X-byte between $80 

and$8F 158 
with an X-byte of $00 1 57 
indirect-X addressing 13 
indirect-Y addressing 13 
input(s) 
analog 113 
device 40 
parameters [116] 
input/output, file 67 
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interface versus implementation 
76 

warning 99 
interface, SOS 76 
intermediate form, bank-switched 

addresses as 32 
.INTERP [139] 

interpreter(s) 5, 16, 118-125, 145, 
[132] 

and modules 144 

BASIC 145 

code 10 
executing 10 

command [103] 

environment 18-19 

files, creating 143 

language 118 

maximum size of 18 

memory 
placement 18 
requirements of 146 

Pascal 145 

return to 29 

sample(s) 125-142 
listing, complete 131-142 

stand-alone 118 

structure of 119-121 

table within 29, 30 
INTERPRETER FILE NOT 

FOUND [129] 
interpreter-relative relocation 

table [139] 
interpreter's 

stack 19,110 

zero page 19 
interrupt(s) 5,104-115 

conflicts between 104 

handler 5,22,104 

IRQ 22 
and NMI 20 

ranked in priority 104 

summary of 112 



invalid 

address 13 

jumps 29 

regions 15, 16 
INVALID DRIVER FILE [129] 
io buffer [31] 
IO'ERR [72] 
IRQ interrupts 20, 22 
is newline 67, 68, [33] 

J 

JMP 27-28, [139] 
joymode [99] 
joy status [100] 
joystick [99] 
JSn-B [100] 
JSn-Sw [100] 
JSn-X [100] 
JSn-Y [100] 
JSR 27-28 
jumps 29 

inside module 29 

invalid 29 

valid 29 

K 

KERNEL FILE NOT FOUND 

[130] 
key pointer 87, 92 

keyboard 40 

L 

labels xix, 120 

local 127 
language interpreter 1 1 8 
largest possible file 94 
last mod date and time 64,88, 

89-90, [14], [19] 

field 89-90 
LDA 31, [139] 
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leaving ExerSOS [119] 
legal device names 42 
legal file names 59 
length 152, [3], [11], [17], [25], 

[30], [67], [116] 
letters 42, 56 
level 66, [51], [53] 
level, system file 66 
limit 23,122, [75], [78], [83] 
LIMIT 122 

line-termination character 67 

linked list 78 

linker information [133] 

linking 

assembly-language modules 
145 

dynamic loading during 145 
lists 

required parameter 129, 

150-152 
optional parameter 152-154 
loading 

dynamic, during linking 145 
assembly-language modules 
145 

routine [134] 
loading_address 120,121 
locating a byte in a standard 

file 98 
logical 

block 77 
device 53 

byte position 98 

device(s) 40 
accessing a 41 
multiple 54 

structures 76 
logical/physical device 

correspondence 54 
loop, increment 124 
low-order nibble [117] 
LVLERR [56] 
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machine 
abstract 2 

storing the state of the 110 
macro, SOS 126 
Makelnterp [121-122] 
management calls 

device 5 

file 5 

memory 5 

utility 5 
manager, resource 2-3 
manual movement of EOF and 

mark 66 
manuf id 45, [70] 
manufacturer 45 
mark 51 , 53, 64-65, 68, 97, 98, 

[45] 

movement of, automatic 65 
movement of, manual 65-66 

marker, current position 51 

master index block 94, 96, 97 

maximum 

number of access paths 53 
capacity of a file 94 
number of index blocks 94 
size of an interpreter 1 8 

MCTOVFL [127] 

media, removable 53, 54 

medium 42, 53 

MEM2SML [127] 

memory 6-7, 23 

access techniques 27-38 
addressing, bank-switched 

10-13 
allocation 25,121 
bookkeeper 7 
call(s) 25-27 
errors 160 
conflict 121 
avoiding 121 
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management 7 

calls 5 
obtaining free 121-124 
placement 
interpreter 18 
module 144 
SOS device driver 21 
SOS Kernel 20 
S-bank 19 
segment 7 
size, maximum 6, 10 
unswitched 28 
messages, error [1 23-1 30] 
min_version 81 , 84, 88 
mode(s) 

absolute addressing 29 
addressing 10-16 
enhanced addressing 8 
newline information 67 
zero-page addressing 29 
indexed 29 
modification date and time 68 
module(s) 5, [132] 
absolute 143 
addressing 27-29 
assembly-language 19,118, 
143-146 
linking 145 
BASIC invokable 145 
creating 146 
driver 41 

execution, bank-switching 

for 30 
formats 146 
loader [134] 
Pascal 145 

program or data access by 145 
relocatable 143, 146, [132] 
multiple 

access paths 52 
logical devices 54 
volumes 54 



N 

name(s) 60, 68 
device 60 
file 58-59,60 
local 59 

parameter 159-160 

volume 55-56, 60 
namejength 80, 83, 87 
naming conventions 76 
new pathname [9] 
NEWLINE 67, 68, 69, 71 , [33-34] 
newline 

character 67 

mode 67 
newline char 67, 68, [33] 
newline-mode information 67 
nibble 

high-order [117] 

low-order [117] 
NMI 114 

interrupts 20 
NMIHANG [127] 
NORESC [72] 
notation xviii 

and symbols xviii 

bank-switched address 15, 
23 

extended add ress 1 5 

numeric xviii 

segment address 23-27 
NOTBLKDEV [56] 
NOTOPEN [72] 
NOTSOS [55] 
NOWRITE [72] 
null characters (ASCII $00) 97 
number(s) 

decimal xix 

device 44 

hexadecimal xiv 

reference 52 

slot 44 
changing 46 
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unit 44 
version 45 
numeric notation xviii.xix 

O 

OPEN 52, 53, 68, 69, 71 , [29-32] 

call, example 128 
operating system 2-3 

defined 2 
operations 

asynchronous 5 

normal indirect 31 

on devices 45-46 

on files 68 

sequential read and write 50 
optheader 120 
opt header length 120 
optFon list "l52, [3], [11], [17], 

[29] ,"[67] 
optional parameter list 152-154, 

[X] 

ORA 31 

order of event queue 109 
organization, code file [132] 
OUTOFMEM [56] 
output device 40 
overview of the Apple 1 1 1 3-8 
OVRERR [54] 

P 

page(s) 23, [31], [78], [81], [83] 

part of segment address 25 
parameter(s) 

format of a name 159 

input [116] 

list, 

optional 152-154, [x] 
required 129, 150-152, [x] 

name 159-160 

passing 145 

pointer 145 



parent_entry_ length 85 
parent entry number 85 
parent pointer 85 
pami_count [xi] 
parm_list 149 
Pascal 118, 143, [132] 

and BASIC modules 145 

assembler 145, [134] 

interpreter 145 

prefix 62 

program 145 

versus SOS prefixes 62 
path(s) 

access 52 
information 64-66 
multiple 52 

maximum number of 56 
pathname [3], [7], [9], [11], [17], 

[25], [29] 
pathname 52, 59-61 

full 62 

partial 61-62 

syntax 60 

valid 61 
PERFORM 145 
period 42, 56 
peripheral device 8, 104 
physical device 40, 54 

correspondence with logical 
devices 54 
PNFERR [54] 
point, decimal xix 
pointer(s) 31,69,152 

address extension 154-159 

byte order of 79 

comparing two 37 

direct 154, 155-156 
to current 156 
toX-bank 155 

extended 123 

fields 79 

incrementing a 36-37 
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indirect 154, 156-159 

manipulation 36-38 

parameters 145 

preceding-block 78 

self-relative [136], [138] 

three-byte 98 
POSNERR [55] 
prefix(es) 60,61-62 

Pascal 62 

restrictions on 62 

SOS 62 
versus Pascal 62 
.PRINTER [111] 
printers 40 
priority of zero 108 
priority-queue scheme 1 08 
.PRIVATE [138] 
.PROG [136], [139] 
procedure(s) [135], [136] 

attribute table [136] 

code [136] 

dictionary [135] 
entries [136] 
PROCEDURE NUMBER [138] 
procedure-relative relocation 

table [139] 
processing an event 106 
Processor, Apple III xvii 
Product Support Department 45 
program 

execution, restrictions on 14 

exiting from 66 
programming 

assembly-language xiii 

restrictions, circumvention of 
SOS 3 
psuedo-opcode(s) [136] 

.FUNC [136] 

.PRIVATE [138] 

.PROC [136] 

.PUBLIC [138] 
.PUBLIC [138] 



Q 

queuing an event 106 
R 

range, X-byte 15 
READ 67,68,71, [35-36] 
read and write operations, 

sequential 50 
read-enable bit [12], [18] 
reading a directory file 91 
ref num 52, 64, 67, [2] , [29] , [33] , 

[35], [37], [39], [49] 

[41], [43], [45], [47] 
references, relocation [138] 
regions 

invalid 15, 16 

risky 15,16 
release memory 25 
RELEASE_SEG 27, [87] 
relocation 146 

constant [138] 

information 145 

references [138] 

table(s) [138] 

base-relative [138] 

interpreter-relative [139] 

procedure-relative [139] 

segment-relative [139] 
RELOCSEG NUMBER [138] 
RENAME 69,90, [9-10] 
req_access [30] 
request count [35], [37] 
REQUEST_SEG 25, 121 , [75-76] 

call 30 
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